Creating API Documentation

[jdw2465]

I have started a new group on LinkedIn ("Technical Writers and SDK Doc") to spark discussions about methods being used to generate and build SDK documentation. I've asked MadCap whether any of their customers generate SDKs with Flare. Mike Hamilton mentioned that Microsoft does this (code comments-to-XML get put into snippets).

I was surprised to learn that there are no ongoing discussions here on MadCap forums for API doc development. I'm equally surprised that Flare (nor any other of the other popular doc tools) support SDK documentation development, because SDK doc does have a number of unique requirements, like getting self-documented (code comments) out of the source code and into the documentation, linking to third-party doc online (e.g. MSDN), etc.

I'd be interested in knowing if there are other Flare users willing to share/speak to this? Do you build SDKs using Flare? How do you get auto-generated code-comments from source code into Flare? And if you have a large API set to document, have you found any performance issues with Flare (as I have, including a number of crashes after importing a CHM file containing some 5K topics, which isn't unusually large for SDK doc).

I'd love to hear the thoughts of one and all on this subject.

Thanks in advance for your time and willingness to share.

[LeslieT]

I have great interest in this subject.

We have an extensive REST API. I have a nearly 400 pages worth of API documentation in a Flare project, but finding ways to automate some of this would be awesome. It is incredibly time-consuming. Being able to take a WADL and XSD and then apply an XSLT easily and incorporate them into a project would be a dream.

[jdw2465]

Leslie, so how did you get the 400 topics in there? Word? Copy and paste? Are you using code comments written by developers, or did you have to extract the info from developer brains and write it up yourself? I'm so curious how and what others are doing who are facing this scenario.

I too would give my right arm for a COMPLETE SDK doc solution. And by the way, after this first gigantic product SDK, I have another task to tackle a Web SDK that will be very REST-intensive.

I'm interested to know how you got to where you are now. And thanks for the response/post.

[LeslieT]

It has been a long hard slog.

When we first started, the REST API wasn't too big and just covered the basics. One of the developers dumped it all into a Work doc and I imported it to Flare and then did a lot of clean up and re-org, etc. Since then it has grown to about 4x that size or more and with each release I have to add new data types and methods (REST paths), as well as any examples that I can dig up. I can get the changes to the schemas pretty easily, but the WADLs are another story. This is now a huge item that is auto-generated with the product build but the order of the items changes so you can't even do a dif to figure out what changed between versions. So I have to go through it manually item by item. For the primary one, the last time I printed, it was 103 pages of code -- ugghh!!

That is what I have been doing.

[LTinker68]

Make sure you guys submit feature requests for this at http://www.madcapsoftware.com/bugs/submit.aspx. The more who submit the request, the sooner (theoretically) it will be implemented.

[jdw2465]

Submitting request!!!! Can I submit 1k times? (<:

[nwilsonm]

We here @ paperthin have been doing this for years...check this out -- you will need to register as a user:

http://community.paperthin.com/commonsp ... /index.htm

And LMK if this is the kind of thing you're interested in producing...

Nancy

[jdw2465]

Nancy, this is the kind of thing we want to produce. Did you have to use a third party tool to extract the code comments for the API reference, or do you have a home-grown method for extracting them directly into Flare?

Love to know your thoughts on this!

Thank you.

[twohlrabe]

I am also interested in this. How did you auto-generate the API information?

[kelly_hochanadel]

We are using Flare to build descriptions for our API reference entities as well. We have an internal utility that scrapes the codebase and creates an XML file of all the REST entities it finds. From there, I import it into Flare and add a <description> field and we write each REST entity record back to a SQL database which has a description column. It's not pretty, but it works.

[plb2hearts]

I've been tasked with creating a project for a REST API. Does Flare support WADL yet? I am very interested in the project posted by paperthin. It's exactly what I need to do. Would love to know if there are resources available so that I don't have to start from scratch. Thanks.

[Msquared]

Just to say I'd be interested in finding out how other Flare users are managing to do this. I think I need to post on the thread so I can be notified of replies.

I already do something similar for some of our database tables. I run a script that extracts the data from the codebase into Flare topic format, then build the Flare output from the auto-generated topics. But I also have SOAP and REST APIs to document and it would be wonderful to have a clean way to do that directly from the sources. Today, as I write this, I'm busy playing catch-up between the documentation and the WSDL again.

[Nina Esile]

I'm just starting to look into this. We've got an API doc created in Word, but now we want to move it to Flare. Hoping for some inspiration!

[ToddPh]

I'm also writing API references in Flare, and while it's not quite the same as writing a full SDK, there are overlaps. I'm eager to read through any experiences folks can share in the hope I'll learn much faster than by blindly stumbling through on my own.

[Nina Esile]

When I pull the text in from Word, I lose the indents (created with spaces because it's code). How do I keep the indent structure created with spaces?

[RamonS]

When I pull the text in from Word, I lose the indents (created with spaces because it's code). How do I keep the indent structure created with spaces?

You may want to look at the <pre> tag, but inserting that in will probably be a clean up task after import. Alternatively, edit the Word document for those section to use non-breaking spaces, maybe those get preserved when importing.

[Nina Esile]

Ramon,

Thanks for your help.

I found this (http://forums.madcapsoftware.com/viewto ... xt+#p85541), which was very helpful and worked.