Move docs from wiki to the project repository itself

[jdufresne]

Moving the docs allows them to more easily be developed in a first-class
manner through pull requests. The docs can stay aligned with code
changes as they happen within the same commit.

For example, as the code gets refactored, docs may become incorrect or
out of date. With the docs in the repository, this can be caught during
development and review.

Contributors can provide reviewable documentaiton-only changes, even
small ones, thus improving the community experience.

An up to date version of the docs were cloned and copied using:

git clone https://github.com/railsadminteam/rails_admin.wiki.git

The docs were left as-is as much as possible. If there are desired
changes, these can now be opened as future pull requests. Articles that
are linked to internally are not included.

Changes to the wiki articles:

• All previous wiki links have been converted to be compatible with
  GitHub flavored Markdown so links continue to work as before.

• Small formatting changes to be compliant with Prettier.

• References to *.coffee files were updated to *.js.

• Renamed index.md to home.md to follow conventions.

• Added an H1 header to all articles which was previously implicitly added by
  the wiki engine.

Once this change lands, the wiki can be removed so as to avoid confusion
for new users.

[coveralls]

Changes unknown
when pulling ee0abe7 on jdufresne:move-docs
into ** on railsadminteam:master**.

[codealchemy]

Some good points made here! This feels worth considering - but I'm not sure how helpful doing a complete overhaul of the docs would be for folks. A few thoughts on the approach / notes

as the code gets refactored, docs may become incorrect or out of date.

True (and inevitable, one could argue), though it doesn't feel like having it alongside the code addresses this. Despite our best intentions, unless there's something to enforce doc updates as a part of the development workflow (such as a linter or failing spec - I'm guessing there's some tooling that could help with this), documentation will always be playing catch-up. Docs would also be tied to releases, which - depending on your perspective - carries its own advantages / disadvantages.

One way to address this is to improve the documentation inline (using rdoc or similar) - which is much harder to miss (and already done in several places).

Contributors can provide reviewable documentation-only changes, even small ones, thus improving the community experience.

The key here, I think, is reviewable changes. I've found the Wiki experience to be very accessible since changes are auditable but don't otherwise require review cycles. Requiring review for documentation updates adds more maintenance work, we'd also need to tweak CI so as to avoid unnecessary burning test resources.

Moving away from the Wiki would also impact (for a time) SEO / search results (maybe something that could be bridged with links / redirects).

Aside from keeping the Wiki or moving forward with this change, another approach could be to set up Github Pages on a separate branch. We would get some of the same advantages seen here (reviewable doc changes) and could set up additional features like a custom domain.

Thoughts @mshibuya ?

[mshibuya]

@jdufresne @codealchemy
Thank you for your opinions. Here's my thoughts on this...

First, what I want to point out is that maintaining documentations is hard. I wasn't there when the decision was made, but I suppose the reason that RailsAdmin decided to put all docs into the Wiki was to offload that maintenance effort broadly to the users, not just maintainers and code contributors. We're already busy on adding features and fixing issues, right?
With that in mind, I hesitate to say that all code contributors must handle all changes to the documentation. Of course the documentation being out of sync with the implementation is a problem, but it will be too much of work for the code contributors.

With that perspective, I think this idea

to improve the documentation inline (using rdoc or similar)

will be worth considering. If that's possible, while addressing the out-of-sync issue, it will also reduce the effort of maintaining the document because when one finishes the implementation the documentation may be halfway-done. All he/she has to do will be adding some explanations to the implementation, and it will be easier than writing documentation in the Wiki from scratch.
But the downsides with it will be

• It requires much work to convert existing docs in the Wiki to inline ones
• The docs become organized based on the code structure, which may be not so intuitive than the current one

I want to explore the possibility of this, by converting a few docs into the inline version and seeing how it looks.
(But it may not be soon enough, when I have time...)

[jdufresne]

The docs become organized based on the code structure, which may be not so intuitive than the current one

IMO, this in particular is a big downside. Right now, the docs are nicely organized as guides and how-tos. By matching docs to the code structure we're now forced into mostly only providing API reference documentation. While that is useful for some use cases, it is often not the best introduction to a new project. I find that usually a mixture of guides and references work out the best.

Perhaps the docs could be hybrid of inline API references and how-tos/guides in the docs directory?

If you'd like to close this PR as wontfix, no worries at all and please go ahead.

True (and inevitable, one could argue), though it doesn't feel like having it alongside the code addresses this. Despite our best intentions, unless there's something to enforce doc updates as a part of the development workflow

Nothing is perfect, but the hope is that when a contributor or reviewer greps the code base for a search term, they will get a hit in the docs as well, allowing them to observe the necessary changes required. This isn't automatic, but still an improvement.