On 08/09/16 00:13, Colin Reese wrote: > What are the cons for a github-hosted wiki again? Well, my only objection would be that it is a third party, but since "we" don't really have a proper organization or funding or anything like that which would naturally be able to "run it ourselfs", every solution would become a third party in any way... So, no, I don't have any cons for Github. > > It really seems to make sense to have all of the source and the how-to > hosted in one place, in an easy to use and modify format. Admin and > source control is easy to use (it is designed for it, after all), > managed, and attached to the repo for owfs itself. This really seems > like the obvious solution to me. > > https://help.github.com/articles/about-github-wikis/ It should be noted that Github wikis and Github pages are two different things:
The Github wiki is inline in the repo UI, and features a basic WYSIWYG editor (seems to support multiple markup methods). Either contributors can edit, or all can edit, directly on site. It doesn't seem easy to do vetting of edits though, i.e. "pull requests" from contributors. Either you allow *everyone* to edit the wiki, or only project collaborators (who can also commit code I guess?). It *is* possible to manually handle the wiki as a git repo, and do merges that way, but not via Github UI. The Github pages are just static files commited to a GIT repo, which are then presented standalone (no github UI) on xxx.github.io (custom domain supported too). For pages, you *can* use the built-in preprocessing framework Jekyll. I tried it out a bit yesterday, you just commit static files the same way, but you can create separate layout files and do some automatic processing such as iterate files in a directory, or data structures etc, and produce appropriate output. So, html/markdown/"jekyll code"/others as input, html as output (which is shown on xxx.github.io). Quite powerful, but requires some manual work. There is no web editor, so you must clone the repo and edit it locally, making the threshold to contribute a bit higher. So both have pros and cons.. Regardless of which one we find most suiting, I'd say we should keep all info in *one* place, and just use the other for pointing to the first place. Don't have half of the info in pages and wiki.. Or...? Perhaps basic info & best practices on Page, and have non-collaborator contributions on wiki, where articles evolve into best practices, which goes to the site? > > Colin > > > On 9/7/2016 3:03 PM, Jan Kandziora wrote: >> Am 07.09.2016 um 21:23 schrieb Johan Ström: >>> Pro: >>> - would be able to properly version it in git >>> - Could integrate with automatic build on push, using pull requests for >>> contribution etc. >>> - static is simple >>> Cons: >>> - Depending on how it's implemented, it could be trickier to contribute. >>> But most contributors are probably somewhat tech-savvy anyway.. >>> >> If we use "simple" markup, we have to pick a person who extends the >> "simple" markup as needed. I don't like the idea of not being able to >> draw a table in a certain way or arrange text around an image just >> because the "simple" markup does not support what I need. It's nice to be flexible, but to what extent? Are there any formatting languages supporting this, that is not manual HTML? I would not want to do manual HTML for the overall content, just because we need special tables in once place. If we go with GH Wiki, their markdown seems to support inline HTML. If we go with GH Pages, we can do whatever we want. >> >> In reality, we don't need this "simple" markup when all the people who >> are contributing to the documentation are developers. If I understand you correct, you want something more powerful, perhaps HTML or other? If so, I don't agree. Its not about making it simple for computer-illiterate people to contribute, it's making it easy for *us* to write docs and not have to worry about writing verbose HTML around everything to make it readable. >> >> It's either user+developers, then cms/wiki is the way to go, or plain >> old html files, with some preprocessing to put each article into a >> common frame, suppling breadcrumbs and a table of contents >> automatically. All inbetween will gives us a headache. In the later option, if we'd use the Github Pages Jekyll approach, its easy to use HTML where needed and Markup (or some other supported language) where needed. >> >> >>> I'm going to lift a followup question: should we stay on sourceforge? >>> Even if Github may be hyped and nowadays used by every granny and her >>> cat, it *is* a lot better than Sourceforge when it comes to git.. and >>> everything around it.. >>> We would certainly not be the first project to leave SF.. They may not >>> yet have covertly bundled installers and what not with owfs, but who >>> knows.. >>> (http://www.infoworld.com/article/2931753/open-source-software/sourceforge-the-end-cant-come-too-soon.html). >>> >> I have some old projects at sourceforge but yes, I've started new >> projects on github only since some years ago. I would never again begin >> a new project on sf.net. >> >> Why? Because sf.net is the yahoo of software. Totally bloated and full >> of bells and whistles you don't want, with the main functions >> complicated and brittle. Good comparison... :) >> >> >> >>> I haven't looked at github pages much more than during writing message, >>> but something like this is tempting: >>> * Move project to github: git hosting, issue handling, pull requests. >>> * Setup new github pages, automatically built by pushing to either main >>> repo or a separate site repo. If we juse sphinx, jekyll, or plain >>> markdown, or something else, I don't know. >>> * Handle contributions to docs and source the same way: pull requests >>> >>> Github could thus handle: GIT, basic descriptions, issues, pull >>> requests, pages (site), releases. >>> However, not mailinglist. We could keep that at sourceforge though. >>> >> I would like to consolidate the ways to report problems and bugs. It's a >> bit tedious to have this at so many locations. Sourceforge does a >> terrible job translating between the different interfaces. >> Any good plan how to migrate this? What should the mailing list be good >> for in the future? Developers only? If yes, who is taking care for >> people reporting problems and bugs on the github tracker? Good questions! Issues and pull requests should always be the problem & bug-reporting location imo. This lists however has a lot of non-bug questions too, more like support request around hardware. Should that become GH issues? Not too sure.. One upside with mailing list is that it reaches your inbox, if you are subscribed. With github you have to watch the project to be notified of new issues etc.. I don't have an answer.. :) >> >> >>> (as it happens, I just created https://github.com/owfs. If we're not >>> going to use it, then at least so no-one else can steal it.. :)) >>> >> Fine. Please add me (ianka) to the organisation. Done >> >> >>>> If we had to rewrite from scratch, that would be an awful lot of work. >>> That it would indeed.. But at the same time, we would need to go through >>> everything and clean out a lot of old/bad examples anyway. I'd say, >>> unless we're to keep the old site totally, we need to go through all >>> pages and move/filter the content. >>> >> This, yes. My concern was about authorship and copyright mostly. >> "© Copyright 2003-2016 - OWFS website" isn't a good thing to start with. Hm. Well that is ambiguous.. I've mailed with Colin off-list concerning the contents origins. I'll see if I can find out the origins of the (C) too. ------------------------------------------------------------------------------ _______________________________________________ Owfs-developers mailing list Owfs-developers@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/owfs-developers
