Advertisement:

Author Topic: Developer documentation  (Read 8911 times)

Offline live627

  • SMF Hero
  • ******
  • Posts: 3,576
  • Gender: Male
  • A light for our dream which is worth everything we could envision today and more tomorrow
    • live627 on Facebook
    • @live627 on Twitter
    • livemods
Developer documentation
« on: May 04, 2012, 01:41:35 AM »
I find the developer docs for SMF seriously lacking. Now, this isn't a problem for me, as I can read the code and gather what I need too know from there. But I recognize that the vast majority of developers cannot do this, either as easily or not at all. S, they turn to documentation, which can attempt to explain the code in plain English, in varying degrees of success.

But, what if the desired document is non-existent?

A quirk snapshot:
  • Function database: Mostly complete; still on the old site. Why hasn't it been moved? I'd assume its gargantuan size is the reason...
  • Global variables: Not done by a long shot. I added a new section today, but I need more help. And here is the problem: most programmers do not want to document. However,, they be the perfect candidates for this task. Any volunteers? :D
  • Package SDK: Needs work. Not done.
  • Hooks: Mostly done.
  • Coding guidelines: When did SMF become MVC--based??
See a list of my mods

I don't accept support PMs. Ever! Your query will be answered much quicker in the public boards. Why don't I want any PMs asking for support?

Offline Arantor

  • SMF Friend
  • SMF Legend
  • *
  • Posts: 58,417
Re: Developer documentation
« Reply #1 on: May 04, 2012, 08:48:48 AM »
Technically, SMF is sort of MVC based, but it's not how one might normally think of MVC, more a sort of hybrid model/controller with views methodology.

Online AngelinaBelle

  • SMF Friend
  • SMF Hero
  • *
  • Posts: 7,142
Re: Developer documentation
« Reply #2 on: May 04, 2012, 11:09:27 AM »
Live627 -- You have done a lot of doc writing in the past few days.

Thank you for the documentation you've just written.

I agree that documentation for developers is lacking.
And I really appreciate contributions from people who know this code inside and out.
I'm just a doc writer, myself :)
And the devs generally hate writing documentation.

It seems to me that the most important thing about this new content you are adding (other than getting the right information in there) is organizing it well. I can see you are using categories in your articles.  That will help.

I have not thouroughly read through your contributions. Do you have any questions about pulling this stuff together?  What do you think of a "developers  page" something like the main page at  http://wiki.simplemachines.org/smf/Main_Page
If you do what you've always done, you'll get what you've always gotten. -- Anthony Robbins

Offline live627

  • SMF Hero
  • ******
  • Posts: 3,576
  • Gender: Male
  • A light for our dream which is worth everything we could envision today and more tomorrow
    • live627 on Facebook
    • @live627 on Twitter
    • livemods
Re: Developer documentation
« Reply #3 on: May 04, 2012, 07:51:26 PM »
Quote
And the devs generally hate writing documentation.
I can imagine. Moreso when they only finger type. Like me.

Quote
Do you have any questions about pulling this stuff together? 
Not sure what you mean? Editing the wiki? Absolutely no problem. Finding older content around the forums and entering it into the wiki? "I assume that is what you mean.

The function database should be transferred to the wiki sometime soon, so everything's all in one place. Then whatever missing tidbits in it can be finished.
- For example, createList(). The only document on what it can work with is buried in a two year old thread started by me asking about it.
- There's more, but they escape my memory at the  moment

Quote
What do you think of a "developers  page" something like the main page
I'm not sure, actually. It may be overkill. I'm content with the standard category page, really.
See a list of my mods

I don't accept support PMs. Ever! Your query will be answered much quicker in the public boards. Why don't I want any PMs asking for support?

Offline Norv

  • SMF Friend
  • SMF Super Hero
  • *
  • Posts: 18,314
  • Blue Wolf
Re: Developer documentation
« Reply #4 on: May 04, 2012, 08:18:51 PM »
What do you think of a "developers  page" something like the main page at  http://wiki.simplemachines.org/smf/Main_Page

Actually, I think it's better. We do have other pages to add, relevant pointers, and it would be best to do so. Some are discussed in another topic here, IIRC. Others are in preparation.

Thank you, live, for the initiative and time for it!

About function database transferring in the wiki: please note that SMF 2.1 and 3.0 (and up, of course), will have phpDoc-style documentation for the codebase. Which means it can be - and will be - automatically generated, and uploaded on the site. I don't really think another way to "transfer" is necessary (function database will remain available for legacy versions of SMF). Other than filling the useful information maybe, from function database, to SMF itself, to its phpDoc function documentation.
To-do lists are for deferral. The more things you write down the later they're done… until you have 100s of lists of things you don't do.
File a security report | Developers' Blog | Bug Tracker

Also known as Norv on D* | Norv N. on G+ | Norv on Github

Offline live627

  • SMF Hero
  • ******
  • Posts: 3,576
  • Gender: Male
  • A light for our dream which is worth everything we could envision today and more tomorrow
    • live627 on Facebook
    • @live627 on Twitter
    • livemods
Re: Developer documentation
« Reply #5 on: May 04, 2012, 08:53:58 PM »
Quote
Actually, I think it's better. We do have other pages to add, relevant pointers, and it would be best to do so. Some are discussed in another topic here, IIRC. Others are in preparation.
How would you like to see it? This, because I don't have any ideas on a good front page.

Quote
Thank you, live, for the initiative and time for it!
Sure. I do lack the time to do it properly sometimes, as may be evidenced from a fulll year of lack of contributions to the documentation.

Quote
About function database transferring in the wiki: please note that SMF 2.1 and 3.0 (and up, of course), will have phpDoc-style documentation for the codebase. Which means it can be - and will be - automatically generated, and uploaded on the site. I don't really think another way to "transfer" is necessary (function database will remain available for legacy versions of SMF). Other than filling the useful information maybe, from function database, to SMF itself, to its phpDoc function documentation.
YAY!! That's great news! But, it generates flat files, although, Smarty (yes, that is the templating system it uses to format its output)) can be modified to inject its values into the database to become new wiki pages (err, I assume MW uses MySQL or equivalent).
See a list of my mods

I don't accept support PMs. Ever! Your query will be answered much quicker in the public boards. Why don't I want any PMs asking for support?

Offline Arantor

  • SMF Friend
  • SMF Legend
  • *
  • Posts: 58,417
Re: Developer documentation
« Reply #6 on: May 04, 2012, 09:43:25 PM »
Quote
YAY!! That's great news! But, it generates flat files, although, Smarty (yes, that is the templating system it uses to format its output)) can be modified to inject its values into the database to become new wiki pages (err, I assume MW uses MySQL or equivalent).

Yes, MW uses MySQL but it doesn't do what you might think it does - you need to have inputs in multiple tables to make it work.

Better would be to have it dump files and then write an import script, sort of like what I did with SimpleDesk's docs, only actually putting them in a DB rather than anything else.

Offline Norv

  • SMF Friend
  • SMF Super Hero
  • *
  • Posts: 18,314
  • Blue Wolf
Re: Developer documentation
« Reply #7 on: May 04, 2012, 09:53:25 PM »
I'm not sure I'm following the latter. Why would you import them to the wiki? They're html pages, generated according to the template chosen (we will want a template fitting for this site though). Once uploaded to a section of this site, they can be browsed, read, consulted. They're function documentation, API documentation, which doesn't need to change other than by changes in the codebase, and regenerating it when necessary.

Am I misunderstanding something? (kinda late around here! :D)
To-do lists are for deferral. The more things you write down the later they're done… until you have 100s of lists of things you don't do.
File a security report | Developers' Blog | Bug Tracker

Also known as Norv on D* | Norv N. on G+ | Norv on Github

Online AngelinaBelle

  • SMF Friend
  • SMF Hero
  • *
  • Posts: 7,142
Re: Developer documentation
« Reply #8 on: May 07, 2012, 07:44:58 AM »
live,

Anything you can do will be great.

The advantage of Main_Page is that it is organized the way WE want it, instead of automatically generated.
The difference is like that between a table of contents and an alphabetized index.

You provide guidelines, doc writers and helpers can help with the writing.

If you do what you've always done, you'll get what you've always gotten. -- Anthony Robbins

Offline emanuele

  • Language Moderator
  • SMF Super Hero
  • *
  • Posts: 14,070
  • Gender: Male
  • THERE'S JUST ME
Re: Developer documentation
« Reply #9 on: August 11, 2012, 04:46:42 AM »
Do you want to discover what I'm doing? Here it is!



Hai bisogno di supporto in Italiano?

* emanuele dislikes "like" and alike

Aiutateci ad aiutarvi: spiegate bene il vostro problema: no, "non funziona" non è una spiegazione!!
1) Cosa fai,
2) cosa ti aspetti,
3) cosa ottieni.

It has been reported to me that I'm being snarky, feel free to be offended by my comments, I'm probably doing it on purpose...or not.

Offline piranon

  • Semi-Newbie
  • *
  • Posts: 25
    • https://www.facebook.com/siam4friend on Facebook
    • @siam4friend on Twitter
Re: Developer documentation
« Reply #10 on: August 21, 2012, 10:09:21 AM »
Thank you very much.

Offline emanuele

  • Language Moderator
  • SMF Super Hero
  • *
  • Posts: 14,070
  • Gender: Male
  • THERE'S JUST ME
Re: Developer documentation
« Reply #11 on: February 01, 2014, 05:38:28 PM »
- For example, createList(). The only document on what it can work with is buried in a two year old thread started by me asking about it.
Since I'm here around:
http://wiki.simplemachines.org/smf/Generic_List
I'd suggest to have a look here:
http://wiki.simplemachines.org/smf/User:Emanuele/codedoc#createList
for both parameters and formatting. ;)
Do you want to discover what I'm doing? Here it is!



Hai bisogno di supporto in Italiano?

* emanuele dislikes "like" and alike

Aiutateci ad aiutarvi: spiegate bene il vostro problema: no, "non funziona" non è una spiegazione!!
1) Cosa fai,
2) cosa ti aspetti,
3) cosa ottieni.

It has been reported to me that I'm being snarky, feel free to be offended by my comments, I'm probably doing it on purpose...or not.

Offline live627

  • SMF Hero
  • ******
  • Posts: 3,576
  • Gender: Male
  • A light for our dream which is worth everything we could envision today and more tomorrow
    • live627 on Facebook
    • @live627 on Twitter
    • livemods
Re: Developer documentation
« Reply #12 on: February 01, 2014, 06:39:15 PM »
I just copied text from the old post.
See a list of my mods

I don't accept support PMs. Ever! Your query will be answered much quicker in the public boards. Why don't I want any PMs asking for support?

Offline Deprecated

  • SMF Hero
  • ******
  • Posts: 3,192
  • Gender: Male
  • I tried being reasonable ....... I didn't like it.
Re: Developer documentation
« Reply #13 on: February 01, 2014, 07:34:20 PM »
Quote
And the devs generally hate writing documentation.
I can imagine. Moreso when they only finger type. Like me.

Just to make things clear, this is not a local phenomenon. As an industry veteran (since the late '60s and Fortran IV) I have always found that people who like to write code are concentrators, figurers, people who relate to the complexity of the machine--but not communicators. They want to convene with their code, not with people. Once the code is working they want to move on to writing more code. (Code is a drug. Docco is not.)

With some, the code is the documentation. Live627 and I have been reading this docco. You read the code and you execute it in your head and go over it often enough and now the docco is in your head. Good for you, not particularly good for anybody else because we have not yet achieved telepathy.

My own personal style--in my career as hardware/software/firmware developer--was to include as much documentation in the code as possible. You could tell my assembly or C code anywhere because I filled up the right side of the page with detailed explanations of what was happening. I easily wrote as many comments as code (based on # of characters in a source file.) That was because I realized the comments were probably the best anybody would ever get.

I once spent several months doing nothing but playing second fiddle to another consultant who couldn't be bothered to write any docco at all, not even comments, and in some horrible test programming language (was it ATLAS?), so since their programmer consultant was their fair haired boy they hired me to do nothing but reverse-engineer his code and write the docco that was part of the customer's contract requirements. Must have docco. They were bad days for me but I got my rate, and my self-opinion of consultants, we are technology whores, we negotiate the rate and then my own personal credo, once we have a contract and a rate, I'll do anything I can to deliver the job for as many hours as I can clock.

But getting back to the point, people who write code do not like to document it, and people who do the documentation are usually separate from those who write the code. In an idea world the code writers would document everything they write. Sadly, at least globally speaking, that won't happen any time soon.

And specific to this or any open source project, developers change, and each developer leaving takes knowledge with them, each new developer has to figure it out all over again.

Mod package authors such as me are in a difficult position. Not working on the whole project we focus only on the features we are working on. Myself, I was absent for 3-4 years and a lot changed, except the code mostly looks so familiar. When I left integration hooks were relatively obscure (I had never heard of the then) but today they are all important, particularly because they make writing (and Mod Squad testing) of mod packages easier -- in both cases less code.

So far I've found docco on the hooks but only at a superficial level. I could benefit from examples, but my only examples force me back to reading the code, anybody's code, to reverse engineer how the hooks work.

So this gets back to that dichotomy: people who write code for the most part do not want to write docco. Most docco (in the universe, not specifically SMF) is written by reverse engineering.

I could easily fix this problem. All I would have to do is to change human nature...

Meanwhile I encourage and applaud all of those who contribute to SMF code documentation in any way. Thanks!
See a list of my mod packages. No support PMs please!

Online AngelinaBelle

  • SMF Friend
  • SMF Hero
  • *
  • Posts: 7,142
Re: Developer documentation
« Reply #14 on: February 04, 2014, 04:56:52 PM »
emanuele, for example.
He writes code.  he writes docs. both the user kind and the code kind.
From time to time, he returns and improves the documentation he has already written for developers.
He is awesome.
If you do what you've always done, you'll get what you've always gotten. -- Anthony Robbins

Offline Deprecated

  • SMF Hero
  • ******
  • Posts: 3,192
  • Gender: Male
  • I tried being reasonable ....... I didn't like it.
Re: Developer documentation
« Reply #15 on: February 04, 2014, 07:53:57 PM »
A coder who does documents is a rare find. I was a hardware/firmware/software consultant for the last 20 years of my career. I referred to myself as an "electronic whore." I would literally do anything for money as long as it was engineering and they paid my rate. I spent many bored days writing docco and dreaming of my dream house. I just bought that house last June! :)
See a list of my mod packages. No support PMs please!

Offline PhuriousGeorge

  • Charter Member
  • Jr. Member
  • *
  • Posts: 157
  • Gender: Male
  • It's not a bug, it's a feature!
    • adamriffe on LinkedIn
    • @PhuriousGeorge_ on Twitter
    • Oasis Gaming Community
Re: Developer documentation
« Reply #16 on: February 04, 2014, 11:22:11 PM »
Yeah, I find writing tech-docs easy. User manuals however is another story

Online AngelinaBelle

  • SMF Friend
  • SMF Hero
  • *
  • Posts: 7,142
Re: Developer documentation
« Reply #17 on: February 05, 2014, 05:37:11 AM »
Some user docs are straightforward and easy to write -- they catalog all the features of the software and where to find and control them.  It is useful to have devs involved in this kind of doc writing, since they are the ones implementing the features, and understand what will ACTUALLY happen when you push that button.

Other docs require more knowledge of what types of "how do I do this" questions really trip up the least experienced users.  In that case, it is really useful to have information from those who are actually helping confused new users through all these step.  The result can be like driving directions.  There are a number of ways you COULD get from point A to point B, but when a friend is driving in to town to visit you for the first time, you give them the most expedient route. 
If you do what you've always done, you'll get what you've always gotten. -- Anthony Robbins

Offline Deprecated

  • SMF Hero
  • ******
  • Posts: 3,192
  • Gender: Male
  • I tried being reasonable ....... I didn't like it.
Re: Developer documentation
« Reply #18 on: February 05, 2014, 03:56:47 PM »
User manuals, developer documentation, specifications, test procedures... I'd write anything, although I preferred writing code and luckily I spent over 90% of my time doing that, mainly because my rates were too high to waste me on docco, but they did it in emergencies like when they were facing a due date for the FDA (it was medical engineering). The way I figured it, a consultant who turns down work is an idiot. Fun work, boring work (docco) got my same full effort. I wish I were doing it today, even docco. One bad thing about consulting is that your contract comes around for renewal periodically, and then one time they say it ain't getting renewed. Buh bye!

The more docco you write the better you get at it until finally you can do it mindlessly. I'd crank up the heavy metal and if any thoughts crossed my mind it was how nice my next month's check would look. :o)

I have to actually think when writing code, but that's fun! Each time I add another feature or kill another bug I get a thrill!
See a list of my mod packages. No support PMs please!

Online AngelinaBelle

  • SMF Friend
  • SMF Hero
  • *
  • Posts: 7,142
Re: Developer documentation
« Reply #19 on: February 05, 2014, 05:34:15 PM »
'Course, Simple Machines documentation doesn't do much for your paycheck...
As always, in a volunteer project, the community is grateful for the contributions of all the volunteers.
And we all especially know that devs would rather dev than docco.

All in all, we probably don't say "thanks you" frequently enough to everyone who does lend a hand anywhere around the project.

Thanks!
If you do what you've always done, you'll get what you've always gotten. -- Anthony Robbins