MCServer Wiki / Book

[bearbin]

There's been a discussion in IRC tonight about the Wiki and the book.

Wiki: http://wiki.mc-server.org
Book: http://book.mc-server.org

Benefits / Downsides of Wiki

+ Lower barrier for entry - no GitHub needed.
+ Easier to search with Google.
+ More logical separation of separate issues.
- Bus-factor of 1 (wudles)
- No coherent voice as there are lots of separate articles written by different people.

Benefits / Downsides of Book

+ You can print it off and read it as a single document.
+ Single document form makes it easy to Ctrl-F
+ Managed on GitHub so it's easy to manage and has higher bus-factor.
+ It's a guide, not just an information dump, the ordering helps with learning.
+ Better design than wiki.
- Increased barrier to entry as it requires basic HTML and a GitHub account.
- Possibly harder to search intelligently - but pages could be split up so Google can work it's magic.

If you have any thoughts about which you would prefer, or any points for either side, please say.

[sphinxc0re]

There is also another method of offering documentation to the users. As @Safwat already mentioned on IRC, we could do both of the sources mentioned above. In that case, the book would be a single-paged version of the wiki which would pull the wiki every time something changes.

[jan64]

IMO, the book should be a quick / simple startup guide and the wiki should contain all the other (more advanced) info.

[LogicParrot]

We aren't Debian, I don't think we need the seperation of a "startup guide" and an "advanced features guide". I believe it all fits in one place.

@bearbin, I don't agree with some of the pros/cons:

• We can resolve the Wudles issue and arrange a more decentralized management.
  
• The Wiki is definitely easier to search, regardless of Google. A wiki enjoys a search engine and an ability to have page redirects (e.g. searching for "configuration" can redirect to the "ini files" article).
  
• The coherent voice issue is something any group-written documentation might suffer from if not managed properly, that includes the book.
  
• The Wiki does not have to be an information dump. It can be a sliced version of the well-arranged book. And the homepage can be the Book's table of contents.
  

I'm in favor of a mirroring approach. Forget "the Wiki" and "the Book". There'd be only "the guide", available in several forms: A single-paged version, a sliced version (happens to be hosted on a Wiki), a PDF, perhaps even a Kindle. Contributions to that guide happen to be Wiki-style, but they're reviewed for coherency and compatibility with the Table of Contents structure as strictly as a git PR. Note that this review necessity is present regardless of the choice, so my proposal does not incur any management overhead.

As far as I can see, this approach has no disadvantages whatsoever, and it enjoys the advantages of both the Wiki and the Book.
If Wudles is unresponsive, we could even set up a new one, so the Bus Factor isn't an issue.

[sphinxc0re]

For the wudles problem: I could export all the current pages and someone could set up a wiki by himself. The wiki ATM has some configuration problems, too. E.g you can't put in links with http

[LogicParrot]

Back at the IRC, I asked if there is any material which does not fit in both the Wiki and the Book. We didn't find examples of non-intersecting material back there. But I think I've found one:
The Mob Status and the PathFinder status threads I made in this forum are Wiki material but not book material. So we have at least 1 non-intersection. Can anyone find more?

[LogicParrot]

I think we have 4 options.

• 0. Leaving it as is. That would be too fragmented and is out of the question.
  
• 1. Keeping the book only.
  
• 2. Keeping the Wiki only.
  
• 3. A hybrid approach where the content is mirrored.
  
• 4. Keeping them both, but creating a very obvious seperating line that ensures no material intersection whatsoever.
  

Unless we choose 1, we should contact wudles and decentralize management, or create a new Wiki.

Regarding option 4, a reasonable seperation could be this:

• Book: Any setup guide, configuration options guide, compilation guide.
  
• Wiki: Only the things not in the book. Including, but not limited to: To-do and Status lists (Mob status, PathFinder status, Missing and done features),
  

If we go with that, the Wiki will survive if it's actually needed or die out of natural selection otherwise.

[LogicParrot]

1 more point: The book can be hosted on a Wiki page to allow everyone to contribute without a Github acckunt. (which is regularly mirrored to the atandalone book)

[tigerw]

Use the GitHub wiki. No need to maintain any additional code/mirroring/extra accounts.

[sphinxc0re]

Any other thoughts on this one?