On documentation



  • I've recently started going through magento, an open-source ecommentre framework for a new project we have. This was suggested to me by a colleague and since I've seen it mentioned here and there online I figured I'd take the time to see what the fuss is about. From what I've seen it's very configurable via it's admin panel, but as far as heavy-duty modding goes there's a serious lack of documentation. Now as a developer I know full well why this is; it's nigh on impossible for a developer to motivate himself to write extensive documentation instead of working on that cool new feature currently in development. 

    The fact remains however that if you're going to develop a community around your product, you need solid documentation, tutorials, examples and so on and so forth. Just because your project is OSS doesn't mean I'll read through a few thousand lines of code to find out wth is going on. And this isn't something that applies to magento only, it happens to myriads of projects that seek to develop a community. So I propose we develop a new acronym, an offshoot of RTFM. How about you Write The Fucking Manual? 



  • The best part is that you can hire people to write manuals.  You don't need to make your developers do it.



  •  @belgariontheking said:

    The best part is that you can hire people to write manuals.  You don't need to make your developers do it.

    FOSStards don't have much money usually.  There are exceptions, and those exceptions usually end up being the FOSS success stories (Mozilla, Eclipse, Ubuntu).



  • @tster said:

    FOSStards don't have much money usually.  There are exceptions, and those exceptions usually end up being the FOSS success stories (Mozilla, Eclipse, Ubuntu).

    Money is imperialist slavery.  FOSS is about freedom and sharing. 



  • @tster said:

    FOSStards don't have much money usually.  There are exceptions, and those exceptions usually end up being the FOSS success stories (Mozilla, Eclipse, Ubuntu).

     

     

    FOSStards can sometimes rely on Mac users to write documention in free time, but then it's really snarky crappy documention.




  • @Helix said:

    FOSStards can sometimes rely on Mac users to write documention in free time, but then it's really snarky crappy documention.
    The setting to change your background color is called "bgcolor" ... On a Mac you wouldn't have to know that, just say aloud "change background color to blue" and POOF! you got a blue background!




  • <font size="7">RISE FROM YOUR GRAVE!</font>



  • @bstorer said:

    <font size="7">RISE FROM YOUR GRAVE!</font>
    Hey burn in hell.

    This showed up in my "Not Read" this morning.  Sometimes old threads do that.  I always assumed it was because something got edited on it.  I thought Helix's post was the rez, but I didn't check.

    So I'll say it again, TRWTF is CS.


Log in to reply