We want your ideas to improve the Wiki!

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.

I do agree putting documentation in the code. That should make a lot of things easier to fine and less pages on confluence. 1+ for this.

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ā€™d assume some place like hairbro. :wink:

3 Likes

Agree with everything you mentioned 1+

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.

Ideas:

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

Make clear guidelines for creating wiki pages Like Wikipedia does here: https://en.wikipedia.org/wiki/Wikipedia:Your_first_article

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.

High effort, low impact: Trumpā€™s hairā€¦

3 Likes

2 Likes

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.

Amazing! Iā€™d love to see you involved in this project when we begin. Your suggestions are great and you have very well thought-out suggestions.

Your notes are being compiled in a document that will be used as our roadmap when we begin this project!!!

1 Like

@ngoel2 i like your ideas! :smile:

2 Likes

Thanks @dkayiwa

@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 :slight_smile:

2 Likes

@ngoel2 keep that fountain flowing! We usually get a number of volunteers who are thirsty for ideas regarding how to contribute! :smile: Innovation and craziness are cousins! :smile:

2 Likes

You mean the famous Linus Torvaldā€™s quote, ā€œTalk is cheap. Show me the code.ā€

@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.

@ngoel2 no worries! Your contributions are well appreciated!

@janflowers data IS being compiled and I believe I will be leading this project! Working with @terry on this.

A post was split to a new topic: Re-organizing our wiki content. Looking for your feedback!

@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.

that would be awesome!! :slight_smile: