Putting documentation in source code is a great idea. Does this mean we will no longer need the wiki? What may be a way forward is to put certain parts of the documentation in github as @ssmusoke suggests, and then maybe leave other parts of the documentation in the wiki. This will mean the wiki may have to stick around, be curated and maintained. Also not all documentation in the wiki is necessarily associated with code and therefore such documentation may make better sense in the wiki.
Almost forgot. A major aspect of the wiki that has to be redesigned is the structure. Like others have commented it is difficult to find information currently because the documentation has become a bit haphazard. We should have a good structure so the wiki can be browsed as well as searched.
Lots of ways. The fundamental challenge of the wiki (no matter where or how it is hosted) is the usefulness of the information is directly related to the amount of energy put into creating & maintaining the information.
I wish we could grant account access in a way that successfully filtered out spammers, so we could be more liberal with privileges, lower the barrier for contributions (e.g., via comments), and get rid of captchas on every edit (e.g., I can post a reply here without entering a captcha).
At one point, I was hopeful Confluence 6.0 would support Live Editing. It would be great if our shared note-taking (notes.openmrs.org) were natively included in the wiki (though copying & pasting after a meeting isnāt that much effort).
Discussions. The wiki can be very useful for shared documentation, meeting notes, etc. Itās not a good tool for discussions (Talk if far better for that).
Authentication (initial load times) can be painfully slow.
Thereās a lot of old content mixed in, making it harder to know what to trust.
In those sections of the wiki that are well-organized, itās pretty easy to know where something new belongs. Where the information is less well organized, itās hard to know where to (or even want to) contribute new information.
Some well thought out high level organization can go a long way in helping make it clear where information can be found. Page naming conventions and thoughtful use of spaces can help find things (Space name is included in search results). Iāve seen Confluence instances that get Space-happy and a big list of spaces can make it harder to find things.
I find most things with a combination of the search box and the outline on the left.
svn.openmrs.org exists for archival purposes. Any references to Subversion would be to the archive. Any information referring to using subversion for development needs to be updated or removed.
IMHO, the secret recipe would be some combination of:
A Documentation Lead. Someone waking up worrying about how we, as a community, are doing with documentation, how we could do better, and helping drive the community to improving documentation each week/month/year. This would not be limited to the wiki, but also include Javadocs, REST documentation, module/app documentation, guides, etc.
Paving the road. Make it easy to do the right thing by getting the high level organization (skeleton) such that itās clearer where people should be putting meat on the bones, making & maintaining a handful of really useful templates so people are more likely to start new content with a template following best practices, and making it easier for people to contribute when they donāt know where something belongs (a tip at the bottom of the page, section(s) specifically designed to add content that doesnāt yet have a home, etc.).
Leveraging GitHub. Modules could definitely leverage best practices in GitHub to document a good README.md to provide background + installation & config instructions and a CONTRIBUTING.md to describe how to contribute. Iām not convinced that moving module documentation to GitHub wiki pages is the right directionā¦ the current state of affairs on the wiki set a pretty low bar, so any change seems like an improvement. I would just be careful not to ignore the pros & cons that favor the wiki over GitHub repo wikis (centralized vs distributed for discovery + user edit rights, allowing non-developer contributions to documentation, etc.). Personally, Iād start with encoureage better and more consistent adoption of README & CONTRIBUTING in GitHub.
Building in sustainable maintenance. Under a Documentation Leadās vision, come up with mechanisms to lower the barrier for people to contribute to ongoing maintenance of documentation. Ideally, at any point that someone sees something that needs to be fixed/updated or has something to contribute, they would know how and the barrier would be low. Some examples might be having a label or two for identifying content that is wrong or out of date (could also include a little javascript widget to add this label through a āWas this helpful?ā question on the page). Another would be creating some scripts that scan the the wiki for new comments, pages that have not been viewed/updated more than x times over the past y months and automatically adding labels to them.
I actually saw Donald Trumpās hair when he was giving a speech on the Boardwalk in Atlantic City, NJ ā that thing was flapping like a birdā¦i expected it to fly awayā¦ definitely a hairpiece.
Low effort, high impact:Reading lists of wiki pages for key topics or by reader
One topic usually requires you to read through a couple of different wiki pages, eg: to understand the OpenMRS data model I had to go through a bunch of different wiki pages. Creating curated reading lists would be helpful to me as a reader exploring a topic.
Make a way for readers to tag articles that require cleanup or are missing documentation like Wikipedia does
And featuring these guidelines front and center on the wiki - like on the Welcome page, or before someone can create their first page or when theyāre about to publish the page. One great guideline I like on Wikipedia is - before you start a new topic/page look to see if one already exists and add to it instead of creating a new one. We do have multiple wiki pages on the same thing!
Quick analysis of authors on the wiki
Dunno if thereās some way to get some data but it seems to me that as a newbie the most useful articles I read on the wiki that I needed to get started were written by the same 5 people (you know who you are). Maybe we need to look into how many people are actually writing stuff on the wiki.
Upvote and downvote pages
Like on Quora so that the good wiki pages rise to the top. The more upvotes to a page the higher its position in the search results.
Medium effort, high impact:
Create an āissue trackerā for topics that are missing wiki pages
Sort of like we create issues for feature requests so that interested documenters (aka āunicornsā - magical creatures that donāt exist) can pick them up and document.
Cleaning up key wiki pages
Maybe the ones that go on the reading lists above can be the first ones that are cleaned up - but this is going to require effort from a dedicated volunteer/ editor!
High effort, high impact:Archiving old and irrelavent pages
Maybe searching by date created to check if theyāre even relevant anymore and moving them to an archive.
Its a culture thing
Now donāt quote me on this but I think poor documentation breeds more poor documentation and creates a culture of documentation laziness in an opensource community.
This is incredibly helpful, Burke. Iām documenting everything youāve suggested into a main document that could potentially serve as the roadmap for this Wiki project.
@jeffneiman ā¦Talk is cheap (no pun intended), Iām not sure I have the bandwidth to follow these up with action (isnāt that the classic dilemma of an organization based on volunteers?) but you can always count on me to be a fountain of ideas, most of which are crazy
@ngoel2 keep that fountain flowing! We usually get a number of volunteers who are thirsty for ideas regarding how to contribute!
Innovation and craziness are cousins!
@ngoel2 - This is awesome! Love that you are thinking about a strategy for approaching this in a systematic way where any number of volunteers could jump in to help. @jeffneiman - sounds like you might be compiling this and maybe, just maybe, leading this project?
If anybody needs access to the wiki and they do not already have it ā ping helpdesk and Iāll handle it. If youāve been around forever and used the wiki before, you still have access. Those who created their accounts ~2months ago ā do not. This was a spam countermeasure ā we need to work on a better solution though. It helped to curb the spam ā which lead to hours worth of deleting spam.
@terry, do you mind if I move your reply to a new topic on coming up with a new/better organization of the wiki content? We could make it a āwikiā post, meaning that you (or anyone else) could make revisions to the outline as people leave feedback & discuss.
