We want your ideas to improve the Wiki!

I spend a few hours and It looks like this type of information is in the wiki but, in different spaces and all over the place. Before I make any changes then we need to decide where this part will be located and then decide what needs to be moved under that page. I don’t want to start moving pages and cause a ruckus.

1 Like

@chagara, do you need elevated access? I’d recommend leaving the Welcome page alone (the page you on sign-in)

sure if u dont mind.I havent changed anything yet. Just adding but, wanted to show what I found so far.

let me know when you need 'em =) Don’t feel like doing work OpenMRS duties like that right now =)

Just whenever. No rush.

I would love the documentation to be versioned alongside the code or module that it documents. For example in a similar way than what is done for the official AngularJS doc. I know that Read the Docs does something along those lines. To be investigated…

Perhaps should we also force modules’ README.md to refer to wiki pages, so that each release would offer the opportunity to review the README file and figure out whether the content of its links are out of date.

1 Like

Just took the words out of my mouth. Module usage documentation, best practices, code examples belongs in version control with the code. Not sure how it can be extracted and brought together into a coherent document format

Documentation on interaction with other modules, platform and ref app architecture and strategy etc that are higher level belong to the wiki.

This, so this!

@ssmusoke, @mksd, @chagara, awesome input!!!

I’d love to get some more input from non-devs as well.

@chagara great point about holding off on restructuring. We’re currently in the phase of gathering ideas and will only restructure when we have a solid plan in place that way we don’t interfere with anyone’s current projects. Also, there are over 900 nested posts in the Wiki, FYI. :open_mouth:

@r0bby is right that the welcome page should be left alone and if it were to be edited in any way, it might be last.

Keep it coming everyone! Great constructive feedback so far!

I wouldn’t be opposed to the wiki going away entirely – but this opinion also comes from one of the guys that has to keep it running sooo :stuck_out_tongue:

Did you know github has a wiki?

@r0bby sounds a little anarchist, to be honest… Lol.

Maybe we could implement some things Github does really well? Any suggestions?

Also. GO TO BED! Hahahah. I’m not sure what timezone you’re in, but I don’t think you’re on Africa time.

Github now supports publishing documentation from a /docs folder https://github.com/blog/2228-simpler-github-pages-publishing?utm_content=buffer00491&utm_medium=social&utm_source=twitter.com&utm_campaign=buffer

What if the wiki itself were a Github project being published via Github pages

1 Like

That would be doable – we use a readthedocs style page as @mksd mentioned. We have… a lot of stuff to migate if we go that route…

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