We want your ideas to improve the Wiki!

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:

I’m sorry I missed this. OpenMRS could stand to improve its infrastructure a bit and simplify things. I should note that your use of anarchist is also wrong.