Feature Request #3879

Split guides from repos

Added by Woody Gilk over 3 years ago. Updated about 3 years ago.

Status:ClosedStart date:03/20/2011
Priority:NormalDue date:
Assignee:Woody Gilk% Done:

0%

Category:Internals
Target version:-
Resolution:wontfix Points:

Description

I think it would be beneficial to split the guide/ directories from each repo into Github wikis, like Bonafide does. This allows the guide to be updated without creating changes to the actual code base (save for submodule updates) and allows anyone to edit the guide, which will increase documentation contributions.

This would simply mean a subtree split to separate the contents and renaming "index.md" to "home.md" to fit Github conventions.

History

#1 Updated by Isaiah DeRose-Wilson over 3 years ago

I think this is a great idea. How does the wiki work for multiple branches (like 3.0 vs 3.1) though? It always seems to use the default branch for me. That's the only issue I see, but maybe I'm doing something wrong.

#2 Updated by Woody Gilk over 3 years ago

I don't really see an issue with it only being for the default branch. Any additional functionality is good.

#3 Updated by Isaiah DeRose-Wilson over 3 years ago

Yeah it's not a big deal. It would be nice if they had an option for switching wiki branches. I think this is a good idea though. Maybe something we should target for 3.2?

#4 Updated by Lorenzo Pisani over 3 years ago

But a commit to the wiki means a commit to the project anyway because you need to track the submodule, no? So what is this actually solving other than adding twice as many submodules to track?

If the goal is to make people browse the docs on GitHub, then I am very much against this. You cannot style those pages and they are very ugly to look through when the amount of information grows past a certain point.

#5 Updated by Woody Gilk over 3 years ago

The goal is to lower the barrier to people contributing to the docs, not to have people read docs on Github. If the docs are linked to the Github wiki, anyone can edit the docs via their browser, without having to clone the repo, send a pull request, etc.

#6 Updated by Kiall Mac Innes over 3 years ago

Anything that lowers the barrier to entry without other complications is a good thing..

But - Would this really help any more than promoting/encouraging the use of the "edit the file" button? The branches issue seems like a big deal to me.. (I've honestly never used GitHub wiki's .. its likely I'm missing something...)

#7 Updated by Jeremy Bush over 3 years ago

I really don't think this lowers any barrier or would increase external participation in documentation writing.

Motivation is the deterrer, not tech. This is just more repos to manage.

#8 Updated by Matt Button about 3 years ago

  • Status changed from Feedback to Closed
  • Resolution set to wontfix

Going to close this as github now provide an easy "fork and edit file" button which makes it easier to contribute.

Also, userguide uses extra markdown formatting (such as [!!]) which github doesn't support

Also available in: Atom PDF