Move repo from pages format to series of markdown docs?

[jessieay]

This guide is currently not linked via https://pages.18f.gov/guides/

I do not find that page particularly useful anyway, though, because there is so much info and no search functionality.

What do others think about making this repo a series of markdown docs rather than an 18f-pages repo? I think that would be a better user experience for my own use case (I always visit this on GitHub anyway) but I am interested to hear what others think.

[monfresh]

In a sense, this is already a series of markdown docs. The website gets generated from the markdown docs. I think it's still valuable to have the content available on the web for those who prefer to read it there.

As for this guide not being linked in the main guides page, that can easily be fixed. And for search, it looks like it's something that can be added if we want. For example, the Content Guide includes a search field: https://pages.18f.gov/content-guide/search/?q=contractions

[jessieay]

@monfresh I guess my question here is: does anybody prefer to read it on the web? I myself am more comfortable with reading / searching for this type of information within GItHub. Feels like an extra layer of indirection, if you will, to link people to the dev guides on a web page when the primary discussions are happening on GitHub. And to me, the discussions are as or more important than the content itself.

Do you prefer to read this content on a web page? If so, why?

[cmc333333]

If moving off pages is a viable option, I'd vote to just shove it all in Github's wiki. Easier to edit for non-devs, out of the box search, very clear emphasis on content. Feels like a step in between a bunch of markdown files and a static site.

[jessieay]

@cmc333333 I would prefer something with version control so that people can propose changes and we can discuss as a group / in a PR. Not sure how we would do that with a wiki -- thoughts?

Also, I think it is OK for the development guide to have a contribution process that is familiar to developers since that is the intended audience. But perhaps you are imagining another audience that I am not?

[cmc333333]

That's a good point. The wiki is version controlled, but not in any PR-friendly way.

I think there's some value in sharing the content as nicely formatted HTML (i.e. pages), even if "power users" only deal with the markdown files in the repo viewer. I get the feeling that that benefit outweighs the overhead of maintaining the stylesheets/templates/etc, but I haven't experienced any pain around that process yet.

[jessieay]

Closed via #20