Re: [sakai-dev] Question about Git documentation on our Wiki

classic Classic list List threaded Threaded
4 messages Options
Neal Caidin-3 Neal Caidin-3
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [sakai-dev] Question about Git documentation on our Wiki

The Contributing.MD does not specifically mention the git reset command and then points back to the Confluence page I reference.

It seems like it would be good to decide where canonical documentation should reside and work as a community on the one place, and deprecate the others. 

2 cents.

-- Neal


On Thu, May 25, 2017 at 9:46 AM, Brian Jones <[hidden email]> wrote:
There's also documentation on GitHub [1], you could probably just copy
the bits from there and put them into the Confluence document.

[1] https://github.com/sakaiproject/sakai/blob/master/CONTRIBUTING.md

Brian Jones
Programmer/Analyst
Information Technology Services
Support Services Building, Suite 4300
Western University
<a href="tel:%28519%29%20661-2111%20x86969" value="+15196612111">(519) 661-2111 x86969
[hidden email]

On 2017-05-25 09:42 AM, Neal Caidin wrote:
> Thanks.
>
> Would you (or someone) be willing to update the documentation to the
> correct order?
>
> I don't want to make the change myself since my understanding is not
> very deep.
>
> -- Neal
>
>
> On Thu, May 25, 2017 at 9:36 AM, Brian Jones <[hidden email]
> <mailto:[hidden email]>> wrote:
>
>     Yes, you need to add a remote reference to 'upstream' before Git knows
>     what/where 'upstream' is.
>
>     Brian Jones
>     Programmer/Analyst
>     Information Technology Services
>     Support Services Building, Suite 4300
>     Western University
>     <a href="tel:%28519%29%20661-2111%20x86969" value="+15196612111">(519) 661-2111 x86969 <tel:%28519%29%20661-2111%20x86969>
>     [hidden email] <mailto:[hidden email]>
>
>     On 2017-05-25 09:23 AM, Neal Caidin wrote:
>     > Hi Sakai-dev,
>     >
>     > https://confluence.sakaiproject.org/display/SAKDEV/Git+Setup
>     <https://confluence.sakaiproject.org/display/SAKDEV/Git+Setup>
>     >
>     > I was trying this command:
>     >
>     > git reset --hard upstream/master
>     >
>     >
>     > but it wouldn't work until after I did this:
>     >
>     > |git remote add upstream ||<a href="https://github.com/sakaiproject/sakai|" rel="noreferrer" target="_blank">https://github.com/sakaiproject/sakai|
>     <<a href="https://github.com/sakaiproject/sakai|" rel="noreferrer" target="_blank">https://github.com/sakaiproject/sakai|>
>     > <https://github.com/sakaiproject/sakai
>     <https://github.com/sakaiproject/sakai>>
>     >
>     >
>     > Are they in the wrong order on the documentation?
>     >
>     >
>     > Thanks,
>     >
>     > Neal
>     >
>     >
>     >
>     > --
>     > You received this message because you are subscribed to the Google
>     > Groups "Sakai Development" group.
>     > To unsubscribe from this group and stop receiving emails from it, send
>     > an email to [hidden email]
>     <mailto:[hidden email]>
>     > <mailto:[hidden email]
>     <mailto:[hidden email]>>.
>     > To post to this group, send email to [hidden email] <mailto:[hidden email]>
>     > <mailto:[hidden email] <mailto:[hidden email]>>.
>     > Visit this group at https://groups.google.com/a/apereo.org/group/sakai-dev/
>     <https://groups.google.com/a/apereo.org/group/sakai-dev/>.
>
>

--
You received this message because you are subscribed to the Google Groups "Sakai Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/a/apereo.org/group/sakai-dev/.
Neal Caidin-3 Neal Caidin-3
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [sakai-dev] Question about Git documentation on our Wiki

We do have a plan to start using Jira again for Gradebook issues. I'll write a quick update on that right now.

-- Neal


On Thu, May 25, 2017 at 3:10 PM, Brian Jones <[hidden email]> wrote:
Agreed. I've been vocal in the past about my distaste for the dichotomy
approach. The same problem exists regarding JIRA vs GitHub Issues.

Brian Jones
Programmer/Analyst
Information Technology Services
Support Services Building, Suite 4300
Western University
<a href="tel:%28519%29%20661-2111%20x86969" value="+15196612111">(519) 661-2111 x86969
[hidden email]

On 2017-05-25 02:23 PM, Neal Caidin wrote:
> The Contributing.MD does not specifically mention the git reset command
> and then points back to the Confluence page I reference.
>
> It seems like it would be good to decide where canonical documentation
> should reside and work as a community on the one place, and deprecate
> the others.
>
> 2 cents.
>
> -- Neal
>
>
> On Thu, May 25, 2017 at 9:46 AM, Brian Jones <[hidden email]
> <mailto:[hidden email]>> wrote:
>
>     There's also documentation on GitHub [1], you could probably just copy
>     the bits from there and put them into the Confluence document.
>
>     [1]
>     https://github.com/sakaiproject/sakai/blob/master/CONTRIBUTING.md
>     <https://github.com/sakaiproject/sakai/blob/master/CONTRIBUTING.md>
>
>     Brian Jones
>     Programmer/Analyst
>     Information Technology Services
>     Support Services Building, Suite 4300
>     Western University
>     <a href="tel:%28519%29%20661-2111%20x86969" value="+15196612111">(519) 661-2111 x86969 <tel:%28519%29%20661-2111%20x86969>
>     [hidden email] <mailto:[hidden email]>
>
>     On 2017-05-25 09:42 AM, Neal Caidin wrote:
>     > Thanks.
>     >
>     > Would you (or someone) be willing to update the documentation to the
>     > correct order?
>     >
>     > I don't want to make the change myself since my understanding is not
>     > very deep.
>     >
>     > -- Neal
>     >
>     >
>     > On Thu, May 25, 2017 at 9:36 AM, Brian Jones <[hidden email] <mailto:[hidden email]>
>     > <mailto:[hidden email] <mailto:[hidden email]>>> wrote:
>     >
>     >     Yes, you need to add a remote reference to 'upstream' before Git knows
>     >     what/where 'upstream' is.
>     >
>     >     Brian Jones
>     >     Programmer/Analyst
>     >     Information Technology Services
>     >     Support Services Building, Suite 4300
>     >     Western University
>     >     <a href="tel:%28519%29%20661-2111%20x86969" value="+15196612111">(519) 661-2111 x86969 <tel:%28519%29%20661-2111%20x86969>
>     <tel:%28519%29%20661-2111%20x86969>
>     >     [hidden email] <mailto:[hidden email]>
>     <mailto:[hidden email] <mailto:[hidden email]>>
>     >
>     >     On 2017-05-25 09:23 AM, Neal Caidin wrote:
>     >     > Hi Sakai-dev,
>     >     >
>     >     > https://confluence.sakaiproject.org/display/SAKDEV/Git+Setup
>     <https://confluence.sakaiproject.org/display/SAKDEV/Git+Setup>
>     >     <https://confluence.sakaiproject.org/display/SAKDEV/Git+Setup
>     <https://confluence.sakaiproject.org/display/SAKDEV/Git+Setup>>
>     >     >
>     >     > I was trying this command:
>     >     >
>     >     > git reset --hard upstream/master
>     >     >
>     >     >
>     >     > but it wouldn't work until after I did this:
>     >     >
>     >     > |git remote add upstream ||<a href="https://github.com/sakaiproject/sakai|" rel="noreferrer" target="_blank">https://github.com/sakaiproject/sakai|
>     <<a href="https://github.com/sakaiproject/sakai|" rel="noreferrer" target="_blank">https://github.com/sakaiproject/sakai|>
>     >     <<a href="https://github.com/sakaiproject/sakai|" rel="noreferrer" target="_blank">https://github.com/sakaiproject/sakai|
>     <<a href="https://github.com/sakaiproject/sakai|" rel="noreferrer" target="_blank">https://github.com/sakaiproject/sakai|>>
>     >     > <https://github.com/sakaiproject/sakai
>     <https://github.com/sakaiproject/sakai>
>     >     <https://github.com/sakaiproject/sakai
>     <https://github.com/sakaiproject/sakai>>>
>     >     >
>     >     >
>     >     > Are they in the wrong order on the documentation?
>     >     >
>     >     >
>     >     > Thanks,
>     >     >
>     >     > Neal
>     >     >
>     >     >
>     >     >
>     >     > --
>     >     > You received this message because you are subscribed to the Google
>     >     > Groups "Sakai Development" group.
>     >     > To unsubscribe from this group and stop receiving emails from it, send
>     >     > an email to [hidden email]
>     <mailto:[hidden email]>
>     >     <mailto:[hidden email]
>     <mailto:[hidden email]>>
>     >     > <mailto:[hidden email]
>     <mailto:[hidden email]>
>     >     <mailto:[hidden email]
>     <mailto:[hidden email]>>>.
>     >     > To post to this group, send email to [hidden email] <mailto:[hidden email]>
>     <mailto:[hidden email] <mailto:[hidden email]>>
>     >     > <mailto:[hidden email] <mailto:[hidden email]>
>     <mailto:[hidden email] <mailto:[hidden email]>>>.
>     >     > Visit this group at https://groups.google.com/a/apereo.org/group/sakai-dev/
>     <https://groups.google.com/a/apereo.org/group/sakai-dev/>
>     >     <https://groups.google.com/a/apereo.org/group/sakai-dev/
>     <https://groups.google.com/a/apereo.org/group/sakai-dev/>>.
>     >
>     >
>
>

--
You received this message because you are subscribed to the Google Groups "Sakai Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/a/apereo.org/group/sakai-dev/.

--
You received this message because you are subscribed to the Google Groups "Sakai Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/a/apereo.org/group/sakai-dev/.
'Matthew Jones' via Sakai Development 'Matthew Jones' via Sakai Development
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [sakai-dev] Question about Git documentation on our Wiki

I think they have different uses. I believe Github pages is probably a better solution if we have a small coordinated group (or single person) doing most of the documentation, HTML design and management. It allows for more flexibility of layout, themes and structure. However since it uses jekyll there's can be a little learning curve as you mentioned, and since it mostly works via git push you don't want too many people working on the same content as there would be conflict resolution which you don't want. 

I think of Github pages as documentation easily maintained by a web designer and/or documentation specialist. This would seem to be more of a replacement for sakaiproject.org.

Github wiki seems more structured from the start and easily organized, like I'd expect from a wiki. But not overly fancy. We're not building a website here, just a manual. I like how it also has the last revision right on the top of every page. I think they're different.


The problem with both of these, and confluence is that the changes to the code aren't often reflected in the documentation quickly. I mean we try to keep the default.properties updated but even that can be a challenge. I feel like any documentation should have README.md's closer to the source (like in the tool directories as I mentioned), pull from that and encourage developers making significant updates to tools to change these files. Then we'll have minimal specific technical documentation. The wiki is already looking like a good start to me.

On Fri, May 26, 2017 at 8:04 AM Neal Caidin <[hidden email]> wrote:
Overall I'm +1. 

I'm just curious if the group should not consider Github pages over Github wiki? Once we go down on one of this path's with significant content it's unlikely we will change, so I think it is worth a little bit of looking pros vs. cons. 

Andrew Petro makes the  case for Github Pages in the Apereo Lightning talks from January at the 8:20 mark [1].

My understanding of Github pages advantages is that you are separating content from formatting; that you can update the documentation at the same time as you are adding new features through PRs; and you can still edit the HTML directly if need be (I think?).  And you can have more sophisticated HTML layouts, I assume. The downside might be more complexity or at least a learning curve to start using (Jekyll)? But if we think of this as tech documentation maintained by Developers primarily, then perhaps that is not such a big downside? 


[1] Apereo lightning talk Github pages pitch - 8:20 mark - 

On Fri, May 26, 2017 at 12:55 AM, Steve Swinsburg <[hidden email]> wrote:
We should start to move minimal technical documentation to GitHub wiki.

90% of the doco on confluence for getting started with Sakai is too laborious and should be binned. I have my own two page guide in Google docs which I can share/ write in the wiki. 

This is how an awesome GitHub wiki looks:

Cheers
Steve


sent from my mobile

On 26 May 2017 7:12 am, "Adam Marshall" <[hidden email]> wrote:
Moving away from confluence and consolidating would be a great improvement




On Thu, May 25, 2017 at 8:53 PM +0100, "'Matthew Jones' via Sakai Development" <[hidden email]> wrote:

Personally I think we should be phasing out confluence and moving as much of that documentation as possible to Github, but I also know that is a lot of work. We'll still experience the same "out of date" documentation problem over time but I don't know of any super advantages confluence holds over Gthub wiki.

As far as general Sakai issues, I'd *love* to be able to use Github for that but the problem is Sakai's branch/release management and the QA lifecycle is very hard to do there. We'd either have to have a completely different process for that (won't happen in the short term) or Github would have to add more controls and fields to manage that (which also doesn't seem likely short term). Additionally all Sakai projects (LSNBLDR, SAM, KNL, etc) should be merged into SAK.

For all projects not in sakaiproject/sakai, I don't know what I'd vote for Github Issues or Jira. I guess the branch/release management advantages of jira would benefit for those projects too. Maybe they should just have jira projects (if they don't already) with a note in their top level README.md for what to use. I'd love if GitHub issues was better but even with external PM integrations (Zube, HuBoard, Waffle, etc) it didn't seem to have the workflow that seemed like it was the same, and adding that extra service isn't something we want either.

On Thu, May 25, 2017 at 2:20 PM Neal Caidin <[hidden email]> wrote:
We do have a plan to start using Jira again for Gradebook issues. I'll write a quick update on that right now.

-- Neal


On Thu, May 25, 2017 at 3:10 PM, Brian Jones <[hidden email]> wrote:
Agreed. I've been vocal in the past about my distaste for the dichotomy
approach. The same problem exists regarding JIRA vs GitHub Issues.

Brian Jones
Programmer/Analyst
Information Technology Services
Support Services Building, Suite 4300
Western University
<a href="tel:%28519%29%20661-2111%20x86969" value="+15196612111" target="_blank">(519) 661-2111 x86969
[hidden email]

On 2017-05-25 02:23 PM, Neal Caidin wrote:
> The Contributing.MD does not specifically mention the git reset command
> and then points back to the Confluence page I reference.
>
> It seems like it would be good to decide where canonical documentation
> should reside and work as a community on the one place, and deprecate
> the others.
>
> 2 cents.
>
> -- Neal
>
>
> On Thu, May 25, 2017 at 9:46 AM, Brian Jones <[hidden email]
> <mailto:[hidden email]>> wrote:
>
>     There's also documentation on GitHub [1], you could probably just copy
>     the bits from there and put them into the Confluence document.
>
>     [1]
>     https://github.com/sakaiproject/sakai/blob/master/CONTRIBUTING.md
>     <https://github.com/sakaiproject/sakai/blob/master/CONTRIBUTING.md>
>
>     Brian Jones
>     Programmer/Analyst
>     Information Technology Services
>     Support Services Building, Suite 4300
>     Western University
>     <a href="tel:%28519%29%20661-2111%20x86969" value="+15196612111" target="_blank">(519) 661-2111 x86969 <tel:%28519%29%20661-2111%20x86969>
>     [hidden email] <mailto:[hidden email]>
>
>     On 2017-05-25 09:42 AM, Neal Caidin wrote:
>     > Thanks.
>     >
>     > Would you (or someone) be willing to update the documentation to the
>     > correct order?
>     >
>     > I don't want to make the change myself since my understanding is not
>     > very deep.
>     >
>     > -- Neal
>     >
>     >
>     > On Thu, May 25, 2017 at 9:36 AM, Brian Jones <[hidden email] <mailto:[hidden email]>
>     > <mailto:[hidden email] <mailto:[hidden email]>>> wrote:
>     >
>     >     Yes, you need to add a remote reference to 'upstream' before Git knows
>     >     what/where 'upstream' is.
>     >
>     >     Brian Jones
>     >     Programmer/Analyst
>     >     Information Technology Services
>     >     Support Services Building, Suite 4300
>     >     Western University
>     >     <a href="tel:%28519%29%20661-2111%20x86969" value="+15196612111" target="_blank">(519) 661-2111 x86969 <tel:%28519%29%20661-2111%20x86969>
>     <tel:%28519%29%20661-2111%20x86969>
>     >     [hidden email] <mailto:[hidden email]>
>     <mailto:[hidden email] <mailto:[hidden email]>>
>     >
>     >     On 2017-05-25 09:23 AM, Neal Caidin wrote:
>     >     > Hi Sakai-dev,
>     >     >
>     >     > https://confluence.sakaiproject.org/display/SAKDEV/Git+Setup
>     <https://confluence.sakaiproject.org/display/SAKDEV/Git+Setup>
>     >     <https://confluence.sakaiproject.org/display/SAKDEV/Git+Setup
>     <https://confluence.sakaiproject.org/display/SAKDEV/Git+Setup>>
>     >     >
>     >     > I was trying this command:
>     >     >
>     >     > git reset --hard upstream/master
>     >     >
>     >     >
>     >     > but it wouldn't work until after I did this:
>     >     >
>     >     > |git remote add upstream ||https://github.com/sakaiproject/sakai|
>     <https://github.com/sakaiproject/sakai|>
>     >     <https://github.com/sakaiproject/sakai|
>     <https://github.com/sakaiproject/sakai|>>
>     >     > <https://github.com/sakaiproject/sakai
>     <https://github.com/sakaiproject/sakai>
>     >     <https://github.com/sakaiproject/sakai
>     <https://github.com/sakaiproject/sakai>>>
>     >     >
>     >     >
>     >     > Are they in the wrong order on the documentation?
>     >     >
>     >     >
>     >     > Thanks,
>     >     >
>     >     > Neal
>     >     >
>     >     >
>     >     >
>     >     > --
>     >     > You received this message because you are subscribed to the Google
>     >     > Groups "Sakai Development" group.
>     >     > To unsubscribe from this group and stop receiving emails from it, send
>     >     > an email to [hidden email]
>     <mailto:[hidden email]>
>     >     <mailto:[hidden email]
>     <mailto:[hidden email]>>
>     >     > <mailto:[hidden email]
>     <mailto:[hidden email]>
>     >     <mailto:[hidden email]
>     <mailto:[hidden email]>>>.
>     >     > To post to this group, send email to [hidden email] <mailto:[hidden email]>
>     <mailto:[hidden email] <mailto:[hidden email]>>
>     >     > <mailto:[hidden email] <mailto:[hidden email]>
>     <mailto:[hidden email] <mailto:[hidden email]>>>.
>     >     > Visit this group at https://groups.google.com/a/apereo.org/group/sakai-dev/
>     <https://groups.google.com/a/apereo.org/group/sakai-dev/>
>     >     <https://groups.google.com/a/apereo.org/group/sakai-dev/
>     <https://groups.google.com/a/apereo.org/group/sakai-dev/>>.
>     >
>     >
>
>

--
You received this message because you are subscribed to the Google Groups "Sakai Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/a/apereo.org/group/sakai-dev/.

--
You received this message because you are subscribed to the Google Groups "Sakai Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/a/apereo.org/group/sakai-dev/.

--
You received this message because you are subscribed to the Google Groups "Sakai Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/a/apereo.org/group/sakai-dev/.

--
You received this message because you are subscribed to the Google Groups "Sakai Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/a/apereo.org/group/sakai-dev/.

--
You received this message because you are subscribed to the Google Groups "Sakai Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/a/apereo.org/group/sakai-dev/.
Neal Caidin-3 Neal Caidin-3
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [sakai-dev] Question about Git documentation on our Wiki

We didn't get a chance to discuss at Open Apereo (we ran out of time!) but it seems like we are heading towards using the Github wiki for technical documentation. 

Please feel free to task me. I've started a structure on the wiki already. Take a look. Provide feedback and ideas.

I'm +1 on Steve's suggestion to keep it as simple as possible. I can visualize having a top level That is bare bones instructions and then drills down to details and best/common practices.  For example, adding a mail server, adding an ldap server, setting it up so files are stored in your file store instead of the database (maybe also the practice of hosting files on a separate domain?), etc.  If we could get an outline of common practices and  best practices, we can flesh that out over time.

I'm happy to start just starting to move technical documentation over, and hopefully others will join in and assist.

Would we consider release documentation to be "technical"?  
Please take a look at 

And notice how it links to the Sakai 11 functional release notes. Where would these fit in the structure? Should functional release notes exist outside of Github wiki (e.g. stay in Confluence) ?

Cheers,
Neal


On Fri, May 26, 2017 at 7:17 PM, Steve Swinsburg <[hidden email]> wrote:
Yeah we are making a technical manual, not a website. So wiki not pages.

I would expect a tighter integration with the source code within the technical doco, like links to property files etc. And to drop all of the unnecessary doco like how to install Maven etc.

Honestly, getting up and running with Sakai is no harder than two pages of content. Other advanced topics get their own simple page of instruction (setting up LDAP, shibolleth etc).

Cheers
Steve

sent from my mobile

On 27 May 2017 03:34, "Neal Caidin" <[hidden email]> wrote:
Maybe we can discuss a little more at Open Apereo and make sure to update the list with any additional thoughts, ideas, proposal? It sounds like we may be converging on a decision. 

-- Neal


On Fri, May 26, 2017 at 9:25 AM, Matthew Jones <[hidden email]> wrote:
I think they have different uses. I believe Github pages is probably a better solution if we have a small coordinated group (or single person) doing most of the documentation, HTML design and management. It allows for more flexibility of layout, themes and structure. However since it uses jekyll there's can be a little learning curve as you mentioned, and since it mostly works via git push you don't want too many people working on the same content as there would be conflict resolution which you don't want. 

I think of Github pages as documentation easily maintained by a web designer and/or documentation specialist. This would seem to be more of a replacement for sakaiproject.org.

Github wiki seems more structured from the start and easily organized, like I'd expect from a wiki. But not overly fancy. We're not building a website here, just a manual. I like how it also has the last revision right on the top of every page. I think they're different.


The problem with both of these, and confluence is that the changes to the code aren't often reflected in the documentation quickly. I mean we try to keep the default.properties updated but even that can be a challenge. I feel like any documentation should have README.md's closer to the source (like in the tool directories as I mentioned), pull from that and encourage developers making significant updates to tools to change these files. Then we'll have minimal specific technical documentation. The wiki is already looking like a good start to me.

On Fri, May 26, 2017 at 8:04 AM Neal Caidin <[hidden email]> wrote:
Overall I'm +1. 

I'm just curious if the group should not consider Github pages over Github wiki? Once we go down on one of this path's with significant content it's unlikely we will change, so I think it is worth a little bit of looking pros vs. cons. 

Andrew Petro makes the  case for Github Pages in the Apereo Lightning talks from January at the 8:20 mark [1].

My understanding of Github pages advantages is that you are separating content from formatting; that you can update the documentation at the same time as you are adding new features through PRs; and you can still edit the HTML directly if need be (I think?).  And you can have more sophisticated HTML layouts, I assume. The downside might be more complexity or at least a learning curve to start using (Jekyll)? But if we think of this as tech documentation maintained by Developers primarily, then perhaps that is not such a big downside? 


[1] Apereo lightning talk Github pages pitch - 8:20 mark - 

On Fri, May 26, 2017 at 12:55 AM, Steve Swinsburg <[hidden email]> wrote:
We should start to move minimal technical documentation to GitHub wiki.

90% of the doco on confluence for getting started with Sakai is too laborious and should be binned. I have my own two page guide in Google docs which I can share/ write in the wiki. 

This is how an awesome GitHub wiki looks:

Cheers
Steve


sent from my mobile

On 26 May 2017 7:12 am, "Adam Marshall" <[hidden email]> wrote:
Moving away from confluence and consolidating would be a great improvement




On Thu, May 25, 2017 at 8:53 PM +0100, "'Matthew Jones' via Sakai Development" <[hidden email]> wrote:

Personally I think we should be phasing out confluence and moving as much of that documentation as possible to Github, but I also know that is a lot of work. We'll still experience the same "out of date" documentation problem over time but I don't know of any super advantages confluence holds over Gthub wiki.

As far as general Sakai issues, I'd *love* to be able to use Github for that but the problem is Sakai's branch/release management and the QA lifecycle is very hard to do there. We'd either have to have a completely different process for that (won't happen in the short term) or Github would have to add more controls and fields to manage that (which also doesn't seem likely short term). Additionally all Sakai projects (LSNBLDR, SAM, KNL, etc) should be merged into SAK.

For all projects not in sakaiproject/sakai, I don't know what I'd vote for Github Issues or Jira. I guess the branch/release management advantages of jira would benefit for those projects too. Maybe they should just have jira projects (if they don't already) with a note in their top level README.md for what to use. I'd love if GitHub issues was better but even with external PM integrations (Zube, HuBoard, Waffle, etc) it didn't seem to have the workflow that seemed like it was the same, and adding that extra service isn't something we want either.

On Thu, May 25, 2017 at 2:20 PM Neal Caidin <[hidden email]> wrote:
We do have a plan to start using Jira again for Gradebook issues. I'll write a quick update on that right now.

-- Neal


On Thu, May 25, 2017 at 3:10 PM, Brian Jones <[hidden email]> wrote:
Agreed. I've been vocal in the past about my distaste for the dichotomy
approach. The same problem exists regarding JIRA vs GitHub Issues.

Brian Jones
Programmer/Analyst
Information Technology Services
Support Services Building, Suite 4300
Western University
<a href="tel:%28519%29%20661-2111%20x86969" value="+15196612111" target="_blank">(519) 661-2111 x86969
[hidden email]

On 2017-05-25 02:23 PM, Neal Caidin wrote:
> The Contributing.MD does not specifically mention the git reset command
> and then points back to the Confluence page I reference.
>
> It seems like it would be good to decide where canonical documentation
> should reside and work as a community on the one place, and deprecate
> the others.
>
> 2 cents.
>
> -- Neal
>
>
> On Thu, May 25, 2017 at 9:46 AM, Brian Jones <[hidden email]
> <mailto:[hidden email]>> wrote:
>
>     There's also documentation on GitHub [1], you could probably just copy
>     the bits from there and put them into the Confluence document.
>
>     [1]
>     https://github.com/sakaiproject/sakai/blob/master/CONTRIBUTING.md
>     <https://github.com/sakaiproject/sakai/blob/master/CONTRIBUTING.md>
>
>     Brian Jones
>     Programmer/Analyst
>     Information Technology Services
>     Support Services Building, Suite 4300
>     Western University
>     <a href="tel:%28519%29%20661-2111%20x86969" value="+15196612111" target="_blank">(519) 661-2111 x86969 <tel:%28519%29%20661-2111%20x86969>
>     [hidden email] <mailto:[hidden email]>
>
>     On 2017-05-25 09:42 AM, Neal Caidin wrote:
>     > Thanks.
>     >
>     > Would you (or someone) be willing to update the documentation to the
>     > correct order?
>     >
>     > I don't want to make the change myself since my understanding is not
>     > very deep.
>     >
>     > -- Neal
>     >
>     >
>     > On Thu, May 25, 2017 at 9:36 AM, Brian Jones <[hidden email] <mailto:[hidden email]>
>     > <mailto:[hidden email] <mailto:[hidden email]>>> wrote:
>     >
>     >     Yes, you need to add a remote reference to 'upstream' before Git knows
>     >     what/where 'upstream' is.
>     >
>     >     Brian Jones
>     >     Programmer/Analyst
>     >     Information Technology Services
>     >     Support Services Building, Suite 4300
>     >     Western University
>     >     <a href="tel:%28519%29%20661-2111%20x86969" value="+15196612111" target="_blank">(519) 661-2111 x86969 <tel:%28519%29%20661-2111%20x86969>
>     <tel:%28519%29%20661-2111%20x86969>
>     >     [hidden email] <mailto:[hidden email]>
>     <mailto:[hidden email] <mailto:[hidden email]>>
>     >
>     >     On 2017-05-25 09:23 AM, Neal Caidin wrote:
>     >     > Hi Sakai-dev,
>     >     >
>     >     > https://confluence.sakaiproject.org/display/SAKDEV/Git+Setup
>     <https://confluence.sakaiproject.org/display/SAKDEV/Git+Setup>
>     >     <https://confluence.sakaiproject.org/display/SAKDEV/Git+Setup
>     <https://confluence.sakaiproject.org/display/SAKDEV/Git+Setup>>
>     >     >
>     >     > I was trying this command:
>     >     >
>     >     > git reset --hard upstream/master
>     >     >
>     >     >
>     >     > but it wouldn't work until after I did this:
>     >     >
>     >     > |git remote add upstream ||https://github.com/sakaiproject/sakai|
>     <https://github.com/sakaiproject/sakai|>
>     >     <https://github.com/sakaiproject/sakai|
>     <https://github.com/sakaiproject/sakai|>>
>     >     > <https://github.com/sakaiproject/sakai
>     <https://github.com/sakaiproject/sakai>
>     >     <https://github.com/sakaiproject/sakai
>     <https://github.com/sakaiproject/sakai>>>
>     >     >
>     >     >
>     >     > Are they in the wrong order on the documentation?
>     >     >
>     >     >
>     >     > Thanks,
>     >     >
>     >     > Neal
>     >     >
>     >     >
>     >     >
>     >     > --
>     >     > You received this message because you are subscribed to the Google
>     >     > Groups "Sakai Development" group.
>     >     > To unsubscribe from this group and stop receiving emails from it, send
>     >     > an email to [hidden email]
>     <mailto:[hidden email]>
>     >     <mailto:[hidden email]
>     <mailto:[hidden email]>>
>     >     > <mailto:[hidden email]
>     <mailto:[hidden email]>
>     >     <mailto:[hidden email]
>     <mailto:[hidden email]>>>.
>     >     > To post to this group, send email to [hidden email] <mailto:[hidden email]>
>     <mailto:[hidden email] <mailto:[hidden email]>>
>     >     > <mailto:[hidden email] <mailto:[hidden email]>
>     <mailto:[hidden email] <mailto:[hidden email]>>>.
>     >     > Visit this group at https://groups.google.com/a/apereo.org/group/sakai-dev/
>     <https://groups.google.com/a/apereo.org/group/sakai-dev/>
>     >     <https://groups.google.com/a/apereo.org/group/sakai-dev/
>     <https://groups.google.com/a/apereo.org/group/sakai-dev/>>.
>     >
>     >
>
>

--
You received this message because you are subscribed to the Google Groups "Sakai Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/a/apereo.org/group/sakai-dev/.

--
You received this message because you are subscribed to the Google Groups "Sakai Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/a/apereo.org/group/sakai-dev/.

--
You received this message because you are subscribed to the Google Groups "Sakai Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/a/apereo.org/group/sakai-dev/.

--
You received this message because you are subscribed to the Google Groups "Sakai Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/a/apereo.org/group/sakai-dev/.



--
You received this message because you are subscribed to the Google Groups "Sakai Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To post to this group, send email to [hidden email].
Visit this group at https://groups.google.com/a/apereo.org/group/sakai-dev/.
Loading...