First of, I agree that writing all content in HTML, even if ever so basic HTML, is tedious when I just want to write text. Having to write <i>italic</i> instead of just *italic* does become quite tiresome in the long run.. Also, I don't want to be forced to click buttons to make my text bold, or to write a heading. So some kind of text markup (not HTML) should regardless be supported for basic writing..
Anyway, when it comes to forcing people to write markup.. there shouldn't really be that much needed for a basic article.. Newlines, bold/italic, highlighting "code".. are we having to low thoughts of our users? After all, it's usually not computer illiterates who goes out to use systems like owfs.. :) Regarding design which someone was talking about earlier, yes it's 2016, and it can look good without being too tricky, we should just use an existing simple theme. And yes, ofcourse we should have something which does transforming and page layout automatically. Imo, preferably without requiring scripts and stuff to be installed locally. -- To take a few steps back.. What is it really that we want to have on this page? Basic info: What is owfs, getting started, details on different devices, basic problem solving. Supported hardware (masters, slaves) Details: Documentation of all flags and nodes in the devices. Possibly just generated from the man-pages, as we have today? (Don't want to keep two places up to date) Build instructions Contribution instructions Internal architecture informations Protocols User stories: Examples, success stories, how I solved X with owfs, tips and tricks. .. what else? A lot of this information probably requires some technical skills to describe, and is also "write once and not very often update it" (in many cases just copypaste from old site, copyright permitting). For those kind of pages, I don't think git & some written markup language should be an issue. If we'd go with Jekyll, one could just fall back on HTML when floating images with specially formatted text is really required. But, for user contributed stuff, success stories etc, it *may* prove to scare of some people.. You would have to fork the repo with the pages, figure out where to put your text, upload, create pull request.. Cannot really be compared to just press Edit and get down to writing... Jan, your last lines talked about alternative to push/pull content. A github hosted page could actually be edited directly in the github UI, there is a Edit button which opens an editor directly. You'd of course have to fork it first, and you still need to do basic markup. But if instructed how to do it, is that too advanced? How do you guys feel about just using the GH wiki? My main concern is that you can either have it fully open for anyone to edit, or closed so you have to be project contributor to edit (which also means you can commit code). Since we probably don't want the later, it would have to be fully open. Is that acceptable? Here is a good example of GH wiki usage: https://github.com/Netflix/Hystrix/wiki Lastly, how about the option to have main docs/site on GH pages, and user contributed pages on a GH wiki? Then you can get both worlds: simple to maintain system via pages, and simple to contribute user-stories via wiki. And also a clear line between user contributed and "official". (Maybe one could even add some hook into the wikis system and have some script pull the wiki repo, and copy it into the pages repo automatically.. not impossible!) Regards Johan On 08/09/16 14:30, Jan Kandziora wrote: > Am 08.09.2016 um 11:52 schrieb Colin Law: >>> Face it, simple markup alone will not give you any contributors. Hell, >>> non-developer documentation contributors don't want to bother with >>> markup at all! >> Wikipedia doesn't seem to have problems getting contributors. >> > Oh, COME ON. At Wikipedia, we have problems getting contibutors and it > was found out is was all about markup. I hate Wikipedia table markup. > It's HORRRIBLE. Even more crampy than plain HTML. > > And Stepano, I'm not arguing for not using a template engine. I think > I've made that clear on my first post. I'm arguing against having a > special markup for the content and expect that to be simple enough for > mere users to contribute. Success stories, etc. > > It isn't. Same with git access or having to install another set of > tools. And especially if they are hooked to python/perl/tcl/lua > whatever, which are preinstalled pretty crappily in many many Linux > distributions, putting in another hurdle for contributing. > > > Please, let us make this as easy as possible. Web based mostly. If there > is an alternative path to push/pull content, okay. But there should be > one simple, web based path people who just wanna give their 2 cents can use. > > Kind regards > > Jan > > ------------------------------------------------------------------------------ > _______________________________________________ > Owfs-developers mailing list > Owfs-developers@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/owfs-developers ------------------------------------------------------------------------------ _______________________________________________ Owfs-developers mailing list Owfs-developers@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/owfs-developers
