Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
Is it my browser that doesn't work with their API online documentation?
The structure of it seems to be very bad compared to the Java API online documentation and the Yii API online documentation.
I am new to Zend Framework, so I wonder, should it be like that?
I think the API is nice, the only problem sometimes they don't give real meaning of arguments
After the API is maybe a bit behind some java examples, but I find the reference guilde quiet impressive and complete. You've got 900 pages describing every piece of the framework with short code snippet that's just wonderful.
Personally I use more often the reference guide then the API documentation.
I've been digging into Zend Framework for about a month now. I'm starting to catch on but I have to agree with the initial comment. The API documentation, at least what is available, is atrocious. What is this Dojo stuff anyway? I would expect a proper, standardized API reference for something as extensive and powerful as the Zend Framework. For an experienced software engineer the reference manual is really introductory material. Once it is digested all that is really needed is a good API reference that clearly shows properties, methods, inheritance tree, with brief descriptions where necessary. Like Java, AS3, etc. I could have saved myself about two weeks of time had I had full access to the API. I don't get it, but I intend to persevere with ZF.
For me the problem is the reference guide simply lists through all the components and has a massive page telling very long-haul uses of each component with no sort of scope of where said code should appear in your work flow.
I believe it should be re-factored to be like CakePHPs documentation, where each page is targeted at getting a specific task done, like "Saving Your Data", "Deleting Data", "Validating Data" and so on.
Real life examples with context are a lot more useful then the Zend Docs where I tend to have to guess where certain variables (commonly $db) come from - and in full MVC cases, does't even apply.
Related
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 8 years ago.
Improve this question
I have looked at many articles regarding REST and its design implementation for an API. I have a couple of questions however, and maybe they are simply opinionated as there is no "one fits all solution" to REST or API development in general.
Note that these questions are in regards to contacting and receiving requests from an SDK.
My questions are both in regards to the URI form, as I believe it is called. I have seen this represented in a few ways, but my big concern is about versioning and "dynamic" sections.
For my first question (version'ing) I have seen the following approached used often.
/customers/accounts/V3.4/customer_id/1234
/customers/accounts/V3.5/customer_id/1234
Developers would implement this by keeping a general version class, and as they make calls it would grab whatever version the developer has setup. So if they ever wanted to move up to a new API version they would just have to modify the V#.# in one location. I am wondering how good of an this idea is in practice, especially for an SDK. My general thoughts are that this is OK. I believe this as versions are clearly pointed out. If a change needs to be made it is simply a matter of updating your version's call. With an SDK in mind, using an old API won't break anything as if they do not update for awhile then their API request will still be fine, but will route through an older endpoint.
Question 1. Is version'ing using the approach above okay for API updates? Pro's/Cons?
The second question about dynamic values can be seen as follows.
/customers/V4.3/{customer_id}/account
versus
/customers/accounts/V3.4/customer_id/1234
I am not sure if there is a better trade-off to having dynamic endpoints versus hard coding them as listed above. I say this because what if we have a scenario where we wish to add details to the "account" page.
In the above example customers/V4.3 would not have to be updated, as it still contains the same user list midpoint. We would be able to update the account API without causing a version change. (forgive me if that is a terrible idea). But with the second option we would have to update the versioning as that is a midpoint
Question 2. In the example above, is it better to focus on more static or dynamic endpoints?
Still very new to learning about this, forgive me if I made some bad assumptions or conclusions on API design.
What is the problem with using Parameters ?
IMHO
Things that are dynamic or can change in future should never be part of the URL path.
This is why parameters exists. And the benefit is :-
http://example.com/api/resource/?customer_id=1234&v=3.4
Would be treated the same by your script as:-
http://example.com/api/resource/?v=3.4&customer_id=1234
I don't know the context of the SDK, but I would think hard about requirements before allowing API users to choose the version & perform actions.
Also please take a look https://stackoverflow.com/a/17999251/2489860
This is one of those RESTful debates that can go round in circles. You have three options for specifying the version: the URL, the content type or a custom header. All of them will be considered "wrong" by some folks.
Troy Hunt's written a pretty good discussion around the pros and cons here:
http://www.troyhunt.com/2014/02/your-api-versioning-is-wrong-which-is.html
However, I wouldn't necessarily be too quick to reach for versioning as a solution. You may want to consider side-stepping the issue by using more tolerant consumers, investing in more up-front design or applying the open/closed principle to your APIs.
This argument is expressed in more detail here:
http://martinfowler.com/articles/enterpriseREST.html#versioning
It includes a great quote:
"Some people, when confronted with a problem, think "I know, I'll use versioning." Now they have 2.1.0 problems."
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 8 years ago.
Improve this question
I want to build a simple blog which contains:
A home page with blogs listed in the typical fashion: Title and content, plus read more to open a single entry.
A publish area: Title and Content
admin area to delete and modify posts.
No need for tags, users, or dates.
Take a look at this draft:
I have been looking for tutorials on the internet, but haven't found something simple enought to start working with.
EDIT
Found two nice tutorials. Haven't tested them, but looking at the
comments they seem reliable.
In this tutorial the steps look pretty straightforward and basic.
I'm still a noob in OOP, so this might be right for me:
http://css-tricks.com/1907-php-for-beginners-building-your-first-simple-cms/
This one is more elaborated, it contains users, dates, and tags. I
put it here for future reference:
http://net.tutsplus.com/tutorials/php/how-to-create-an-object-oriented-blog-using-php/
But since you can't use WordPress, what do you need?
You obviously got a pretty concrete idea of how to build it. I think you should refine that further, and start building.
Don't overdo it in the beginning. Start by designing a very simple blog. Each post containing just a title and contents. Skip the use of WYSIWYG editors, and advanced admin options. Just make a view page for a post, a view page for the list (chronological), and an admin page to edit or add posts. Publishing can be done by just adding a simple 'published' field, which you can toggle using a checkbox.
Don't bother with users yet. Just use basic authentication.
If you stick to those simple definitions, you should be able to get a working blog in a short time. After that, you will have some idea of the possibilities (of your possibilities too) and you'll be able to build on the base you got.
If there would be a very extensive tutorial on building a blog, you would eventually still just be copying the samples in that tutorial. It's more fun to think of something yourself and search or ask help for specific problems you run into.
Maybe you will have to start over at some point. Remember, if you build something for the second time, you'll build it faster, and it will be better.
But it won't be good until the third time. ;)
Just do it. If you want to learn anything, simply figure it out. This is straightforward stuff. It'll teach you basic HTTP processing, some simple DB design and integration. Set up PHP/Perl/Python/Java/R/Common Lisp, add in MySQL or SQLite or whatever, follow a couple of HOWTOs, and just do it.
Really, you "don't need us" for this. Just break it down in to pieces. What are the right pieces? Whatever feels right to you. Seriously, unless you plan on hosting it to the wild world with some sensitive information, you really have nothing to lose here by just doing it yourself and pulling it off with amazing perfection or having it come out as a complete disaster. Both are rewarding in its own way.
If you have a specific question about a specific piece, you can come back, or head over to ServerFault, but you will likely be able to pull this off with even a teeny bit of persistence.
So just do it. Grab the keyboard by the plug and work the problem. It's better this way.
Found two nice tutorials. Haven't tested them, but looking at the
comments they seem reliable.
In this tutorial the steps look pretty straightforward and basic.
I'm still a noob in OOP, so this might be right for me:
http://css-tricks.com/1907-php-for-beginners-building-your-first-simple-cms/
This one is more elaborated, it contains users, dates, and tags. I
put it here for future reference:
http://net.tutsplus.com/tutorials/php/how-to-create-an-object-oriented-blog-using-php/
For me this is just great run on tornado and app engine very basic and very good but i don't like comments and fb plugins etc try it source code.
A previous ver without tornado is also available: GitHub
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 7 years ago.
Improve this question
Im trying to find a piece of software to help a small (~3-5 people) team write A) a user guide and B) an API reference for the extensible parts of the software. We quite like the idea of using a wiki of some form, but have a few specific requirements:
The ability to export the manual(s) into both online and offline readable forms (eg, a bunch of HTML files that can be put on a web server or read locally)
Automatically create pages from XML documentation. We are writing in VB.Net/C#.Net, and most of the API specific stuff already has XML documentation comments. It would be great if the API portion of the manual could specify the classes, methods, arguments etc, but also allow the writers to link to these pages from others. (eg, have a page that details the foo class, and be able to have a page that details how to do some general task with the API link to the page for the foo.increaseBarCount() method).
That's just about it, other than the obvious ('easy to use', 'do all the writing for me so that i can get out of the tedium of writing technical documentation', 'not cause a global thermonuclear war').
Does such a piece of software exist? Can a similar system be cobbled together using mediawiki extensions?
As to "automatically create pages from XML documentation", the obvious solution would by doxygen. It creates documentation (HTML, PDF, WinHelp ...) from special doc comments embedded in source code. It handles Javadoc comments, Qt style comments and XML comments. If you generate HTML, the page names are predictable, so easy to link to; doxygen can also create internal links automatically. If you use other formats, you can probably embed some sort of anchor to refer to page names, but I'm not quite sure about that.
With respect to general documentation, we have good experiences with using a wiki. We use MediaWiki (of Wikipedia fame), but any decent wiki will probably do.
We have never tried printing it, but Google shows various solutions for printing from MediaWiki, so you can probably make something work without too much hassle.
The main thing we like about using a wiki for docs is that you can easily change them when you detect a mistake; that keeps them fresh. Also, no worries about having an outdated copy.
You could check out Atlassian Confluence. I believe that they have a free version (possibly just an offer, so you may end up paying in the long run, don't know) for small teams. They also have an API, so it wouldn't be too hard to write a utility to extract the XML C# documentation and create pages from it using the API, if nothing already exists.
The wiki is easy to use and is used quite a bit by open source projects. You can look at
the ANTLR Documentation, which is Confluence, for an example.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
As the years go by we get more and more applications. Figuring out if one application is using a feature from another application can be hard. If we change something in application A, will something in application B break?
We have been using MediaWiki for documentation, but it's hard to keep the data up-to-date.
I think what we need is some kind of visual map of everything. And the possibility to create some sort of reference integrity? Any ideas?
I'm in the same boat and still trying to sell my peers on Enterprise Architect, a CASE tool. It's a round trip tool - code to diagrams to code is possible. It's a UML centric too - although it also supports other methods of notation that I'm unfamiliar with...
Here are some things to consider when selecting a tool for documenting designs (be they inter-system communication, or just designing the internals of a single app):
Usability of the tool. That is, how easy is it to not only create, but also maintain the data you're interested in.
Familiarity with the notation.
A. The notation, such as UML, must be one your staff understands. If you try using a UML tool with a few people understanding how to use it properly you will get a big ball of confusion as some people document things incorrectly, and someone who understands what the UML says to implement either spots the error, or goes ahead and implements the erroneously documented item. Conversely more sophisticated notations used by the adept will confound the uninitiated.
B. Documentation isn't/shouldn't be created only for the documenters exclusive use. So those who will be reading the documentation must understand what they're reading. So getting a tool with flexible output options is always a good choice.
Cost. There are far more advanced tools than Enterprise Architect. My reasoning for using this one tool is that due to lack of UML familiarity and high pressure schedules, leaves little room to educate myself or my peers beyond using basic structure diagrams. This tool easily facilitates such a use and is more stable than say StarUML. (I tried both, StarUML died on the reverse engineering of masses of code -- millions of lines) For small projects I found StarUML adequate for home use, up until I got vista installed. Being opensource, it's also free.
With all that said, you will always have to document what uses what, that means maintaining the documentation! That task is one few companies see the value in despite its obvious value to those who get to do it. . .
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
What would you suggest for the following scenario:
A dozen of developers need to build and design a complex system. This design needs to be documented for future developers and the design decisions must be noted. These reports need to be made about every two months. My question is how this project should be documented.
I see two possibilities. Each developer writes about the things they helped design and integrate and then one person combines each of these documents together. The final document will probably be incoherent or redundant at times since the person tasked of assembling everything won't have much time to adjust every part.
Assume that the documentation parts from each developer arrive just a few days before deadline. A collaborative system (i.e. wiki) wouldn’t work properly since there wouldn’t be anything to read until a few days before deadline.
Or should a few people (2-3) be tasked with writing the documentation while the rest of the team works on actually developing the system? The developers would need a way to transfer their design choices and conclusions to the technical writers. How could this be done efficiently?
We approach this from 2 sides, using a RUP style approach. In the first case, you'll have a domain expert who is responsible for roughing out the design of what you're going to deliver - with developers chipping in as necessary. In the second case, we use a technical author - they document the application, so they should have a good idea of how it hangs together, and you involve them right through the design and development process. In this case, they can help to polish the design, and to make sure that it matches what they thought was being developed.
We use confluence (atlassian's wiki-like-thing) and document all kinds of different "things". The developers do it continiously, and we push each other for docs - we let peer pressure decide what is necessary. Whenever someone new comes along he/she is tasked with reading through everything and to find out what still is correct. The incorrect stuff is either deleted or updated as a consequence of this. We're happy when we can delete stuff ;)
The nice thing about this process is that the relevant stuff stays and the irrelevant stuff is deleted. We always "got away" from the more formalized demands by claiming that we could always construct the word documents they wanted if "they" needed them. "They" never needed them.
I think alternative 2 is the less agile, because it means a new stage to the project (although it may be in parallel with tests).
If you are in an agile model, then just add documentation (following a guideline) as a story.
If you are in a staged approach, then I would nevertheless ask developers to work on documentation, following some guidelines, and review that documentation along the design and the code. Eventually, you may have a technical writer reviewing everything for proper English, but that would be a kind of "release" activity.
I think you can use Sand Castle to document your project.
Check it out
Sand Castle from Microsoft
It's not a complete documentation, but making sure that interfaces etc. are commented using Doxygen-style comments means writing code and documenting it are closer together.
That way, developers should document what they do. I still think a review by the architect(s) is needed to ensure consistent quality, but ensuring people document what they do is the best way to ensure they follow the architecture.